Creating Makefiles Outside of the MPLAB® X IDE
MPLAB® X Integrated Development Environment (IDE) uses the GNU Make to build its projects. This document explains how to re-create the Makefiles for an MPLAB X IDE project outside of the IDE and how to customize Makefile behavior (modify what the Makefiles do, like change the processor or add extra options) without having to regenerate the file. This page describes how to run Make on the Makefiles from the command line.
Creating Makefiles
Makefiles are created by MPLAB X IDE as needed when compiler options change or when files are added or removed. In addition, the Makefiles can be created outside of the IDE using the utility prjMakefilesGenerator. This utility is a batch file (for Windows® OS) or a shell script (for Linux® OS and macOS®). This utility also allows you to recreate the Makefiles by using the same information the IDE uses, which is stored in the $PROJECT_DIR/nbproject/configurations.xml file for a given MPLAB X IDE project. The first section explains how to create the Makefiles outside of the IDE. Then the rest of the page describes how to modify the behavior of the Makefiles without having to regenerate them for further customization. This latter section of the page applies to the Makefiles created by the IDE or by prjMakefilesGenerator (which should be identical).
The main Makefile file is called $PROJECT_DIR/Makefile. It is created when the IDE creates the project and can be modified by the user. There are some targets such as .build-pre, that can be implemented by the user. This file is never regenerated. The rest of the Makefiles are all regenerated by the IDE or prjMakefilesGenerator. They are of the $PROJECT_DIR/nbproject/Makefile*.mk format.
We recommend that you do not commit these nbproject/Makefile* files into revision control. Instead, use the IDE or prjMakefilesGenerator to reproduce them as needed. See Working Outside MPLAB X IDE with Revision Control Systems for more information.
prjMakefilesGenerator
The prjMakefilesGenerator utility is found at:
- Windows OS: $inst_mplabx\mplab_platform\bin\prjMakefilesGenerator.bat
- Linux OS: $inst_mplabx/mplab_platform/bin/prjMakefilesGenerator.sh
- macOS: $inst_mplabx/mplab_platform/bin/prjMakefilesGenerator.sh
The utility regenerates the nbproject/Makefile* files. If you run the -help argument, you will see:
Terminal
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
<project_path> - path to the MPLAB-X project in the file system
[config_name] - (optional) name of a build configuration to generate the makefile for.
If missing, the makefiles are generated for all the build configurations.
-help - displays this help screen.
-v - verbose processing.
-create=@argfile - creates the project specified by <project_path> after looking at the key=value argument file
-compilers=<path>;<path> - ";" separated list of user specified compiler install directories. When used with -create option, first path will be considered only.
-setoptions=@argfile - set project options in a key=value pair file
-setitems - overwrite project items. Works with -copy, -relative, -itemtype=, -files if non default settings are needed. Defaults to overwriting source and header files, storing new ones with relative paths without copying them to the project base folder.
-copy - specify that provided file paths should be copied to the project base folder. Defaults to false if not specified.
-pathmode= - specify that provided file paths should be treated as relative or absolute paths. Defaults to automatic detection if not specified.
-itemtype= - specify the project item type: sources or headers. Defaults to sources and headers if not specified.
-files="<path>" - provide a file or folder path to consider when overwriting project items.
-files=@"argfile" - provide an argument file with one file or folder path per line.
-mplabx-userdir=<path> - the MPLAB-X user directory (useful if you run MPLAB-X with --userdir).
Makefile generation example: prjMakefilesGenerator /home/usr/prj1@default@custom /home/usr/prj2 /home/usr/prj3@xc16
The tool will generate the makefiles for:
1. The configurations named 'default' and 'custom' of the project named 'prj1'
2. All the configurations of the project are named 'prj2' (all because none in particular is specified)
3. The configuration named 'xc16' of the project named 'prj3'
</path></path></path></path></project_path></project_path></argfile></path>
To run the utility, pass as an argument the MPLAB X IDE project directories where you want to regenerate the Makefiles. You can also specify which configurations to regenerate. If no configurations are passed (no @confName), then all Makefiles for all configurations will be recreated.
We recommend that you pass the -mplabx-userdir=<path> as a parameter. The <path> value is the value shown in the IDE in the Help > About dialog under userdir. This will ensure that prjMakefilesGenerator will have access to the same list of compilers as the IDE.
Makefiles Description
The main MPLAB X IDE project Makefile lives at $PROJEC_DIR/Makefile. This is the Makefile the IDE calls. For each configuration in the project, there is also a Makefile-local-$conf.mk and a Makefile-$conf.mk where $conf is the name of the configuration. The main $PROJEC_DIR/Makefile file will call make again on these configuration-specific files. The Makefile-local-$conf.mk contains macro values that are tied to the host where the Makefile was generated. You have the option of not keeping this file if you want the Makefile-$conf.mk to work in another system. In that case, you can call make, specifying all the values that are normally found in the Makefile-local-$conf.mk to match the host where the make is being run (how to do this is explained later on).
If you recreate the files with prjMakefilesGenerator, the Makefile-local-$conf.mk will be correct at that point and will work on the machine where it was run.
Make Environment
The make process must be run from a command line native to the OS. This is cmd.exe in Windows OS and any shell for Linux OS or macOS. The make to be run is GNU Make. There are two types of images that can be created when running make:
- A production image
- A debug image
By default, running the make process produces a production image. To have the make process produce a debug image you need to add the following to the make command line:
TYPE_IMAGE=DEBUG_RUN
The debug image contains everything MPLAB X IDE needs to run a debug session. This information is tool-specific. At this point, there is no way to tell the Makefile which tool to build for. This information is hardcoded in the Makefile when it is created based on the values selected in the IDE for each configuration in each project.
Make Environment in Windows OS
Only a specific version of make and other GNU tools (such as rm) may be used as discussed below.
When you install MPLAB X IDE, the following directory will be created:
C:\Program Files\Microchip\MPLABX\vx.xx\gnuBins\GnuWin32\bin
This directory contains the gnuWin32 tools. You must use these tools to run the make process. You cannot use Cygwin or any other GNU port.
Make sure the path above is the very first thing in your %PATH% environment variable:
c:> set PATH=C:\Program Files\Microchip\MPLABX\vx.xx\gnuBins\GnuWin32\bin;%PATH%
before you run the make process.
Make Environment in Apple® macOS
An out-of-the-box Apple macOS computer contains all the tools needed except the GNU Make executable. You have two choices:
- Install MPLAB X IDE. This will create the file:
/Applications/microchip/mplabx/vx.xx/mplab_ide.app/Contents/Resources/mplab_ide/bin/make
Then, add the directory where Make is to your path before you run the make process:
export PATH=/Applications/microchip/mplabx/vx.xx/mplab_ide.app/Contents/Resources/mplab_ide/bin:$PATH - Install the X tools which will install the make in /usr/bin/make.
Make Environment in Linux OS
Install MPLAB X IDE to create the file:
/opt/microchip/mplabx/vx.xx/mplab_ide/bin/make
Add /opt/microchip/mplabx/vx.xx/mplab_ide/bin to your path.
Makefile Interface
To remove all target files for a given configuration:
- Change the directory to $PROJECT_DIR.
- make -f nbproject/Makefile-debugOption.mk SUBPROJECTS= .clean-conf
This will clean the target files for the debugOption configuration.
To remove all target files for all configurations:
- Change directory to $PROJECT_DIR.
- make clobber
To run the Makefile for a given configuration:
- Change directory to $PROJECT_DIR.
- Set environment variables to override values in the Make process.
- make -f nbproject/Makefile-$CONFIGURATION_NAME.mk SUBPROJECTS= .build-conf where $CONFIGURATION_NAME is the name of the configuration Makefile to be run.
For a configuration called default:
make -f nbproject/Makefile-default.mk SUBPROJECTS= .build-conf
The output for a configuration is one of the debug ELF files. The production image will be a HEX file. $PROJECT_NAME is the name of the project.
dist/$CONFIGURATION_NAME/debug/$PROJECT_NAME.debug.elf dist/$CONFIGURATION_NAME/production/$PROJECT_NAME.production.hex
Environment Variables to Control the Make Process
There are four ways to set the variables that control the Make process:
- Use environmental variables, and call Make with the -e option:
$ export MP_CC=/opt/microchip/xc16/v1.21/bin/xc16-gcc
$ make -e - Set the variables in the command line when calling Make. For example:
$ make MP_CC=/opt/microchip/xc16/v1.21/bin/xc16-gcc - Create a nbproject/Makefile-local-$conf.mk for the machine in use. Include the values of the environmental variables in it.
- Let prjMakefilesGenerator create a custom nbproject/Makefile-local-$conf.mk file for the machine.
Variables that are not overridden will take the values of the macros in the Makefile. The Makefile contains a section that has all of the default values for these macros. So, override whatever you need and the rest will be taken care of by the default values in the Makefile.
When a path is to be supplied in Windows®, it must be entered like this:
"C:/Program\ Files/Microchip/xc16/bin/xc16-gcc.exe"
Use "/" for directory separators, and escape space characters with "\". Finally, quote the whole thing when you run it from the command line.
Variables to Control Tool Names/Locations
The following variables can be overridden:
| MP_CC | Complete path to C compiler executable name |
| MP_BC | Complete path to Basic compiler executable name |
| MP_AS | Complete path to assembler executable name |
| MP_LD | Complete path to linker executable name |
| MP_AR | Complete path to archiver executable name |
| MP_CC_DIR | Directory to C compiler executable |
| MP_BC_DIR | Directory to basic compiler executable |
| MP_AS_DIR | Directory to assembler compiler executable |
| MP_LD_DIR | Directory to linker compiler executable |
| MP_AR_DIR | Directory to archiver compiler executable |
make MP_CC=/opt/microchip/mplabc30/v3.24/bin/pic30-gcc
# Example Windows:
make "C:/Program\ Files/Microchip/xc16/bin/xc16-gcc.exe"
Variables to Control Processor Selection
The MP_PROCESSOR_OPTION is the main variable that is used to control the processor name. Be aware that different compilers expect the name of the processor to be different. Some append "PIC", some use small “f”, etc. The Makefiles created by MPLAB X IDE have the correct values. When you override these values by using MP_PROCESSOR_OPTION, you must ensure names are correct.
The debug image is produced by a link line, which includes the list of memory regions allocated to the debugger. This list is device-dependent. For example, here is the link line to create the debug image on an MPLAB XC16 project:
"C:\Program Files\Microchip\xc16\v1.70\bin\xc16-gcc.exe" -o dist/default/debug/dsPIC33_ OutsideIDE.X.debug.elf build/default/debug/main.o -mcpu=33FJ128GP710 -D__DEBUG=__DEBUG -omf=elf -DXPRJ_default=default -legacy-libc -mreserve=data@0x800:0x81F -mreserve=data@0x820:0x821 -mreserve=data@0x822:0x823 -mreserve=data@0x824:0x825 -mreserv e=data@0x826:0x84F -Wl,,,--defsym=__MPLAB_BUILD=1,--defsym=__MPLAB_DEBUG=1,--defsym=__D EBUG=1,-D__DEBUG=__DEBUG,,,--script=p33FJ128GP710.gld,--stack=16,--check-sections,--data- init,--pack-data,--handles,--isr,--no-gc-sections,--fill-upper=0,--stackguard=16,--no-for ce-link,--smart-io,-Map="dist/default/debug/dsPIC33_OutsideIDE.X.debug.map",--report-mem, --memorysummary,dist/default/debug/memoryfile.xml -mdfp="C:/Program Files/Microchip/MPLA BX/v6.00/packs/Microchip/dsPIC33F-GP-MC_DFP/1.3.64/xc16"
The reserve areas (-mreserve above) may change from device to device. If you want to produce different debug images for different processors, it is preferable to change the processor in the IDE and use prjMakefilesRegenerator to recreate the Makefiles.
These are the versions that support the -mreserve keyword or that pass the list of debug regions by using other means. To generate a debug image with the correct debug ranges passed to the linker, you need to run prjMakefilesRegenerator. You cannot simply change MP_PROCESSOR_OPTION.
| Toolchain | First version supported. All versions greater or equal to this version issue -mreserve |
|---|---|
| XC8 | 1.00 |
| XC16 | 1.21 |
| XC32 | 1.30 |
Variables to Control Special Linking Needs
Some tools require special handling of the linker files, facilitated by the macro MP_LINKER_FILE_OPTION.
The XC16 and XC32 toolchains require this option since they need to specify a part name or a file name, depending on whether the project contains a linker script or not.
These variables are explained in detail in their corresponding toolchain section under Special Considerations for Each Language Tool.
Variables to Modify Command Lines
The following _PRE and _POST variables are optional. They exist simply to allow customization of the command line. You can run a make without defining any of them.
| MP_EXTRA_CC_PRE | MP_EXTRA_CC_POST |
| MP_EXTRA_BC_PRE | MP_EXTRA_BC_POST |
| MP_EXTRA_AS_PRE | MP_EXTRA_AS_POST |
| MP_EXTRA_AR_PRE | MP_EXTRA_AR_POST |
| MP_EXTRA_LD_PRE | MP_EXTRA_LD_POST |
Many compilers (such as gcc-based ones) use their main shell program to call the linker/assembler. These command lines, then, are formed of a first section (where MP_EXTRA_XX_PRE is located), and a second section, which is typically passed to the linker/assembler (where MP_EXTRA_XX_POST is located). That is why two macros per tool are needed to allow you to modify the behavior of that tool.
An example of a link line in a gcc-based compiler is:
${MP_CC} -omf=elf ${MP_PROCESSOR_OPTION_LD} ${MP_EXTRA_LD_PRE} -o dist/$(CND_CONF}/${IMAGE_TYPE}/Explorer16PIC24DSC_1.${IMAGE_TYPE}.elf ${OBJECTFILES} -Wl,--defsym=__MPLAB_BUILD=1,--report-mem, -Tp24FJ128GA010.gld${MP_EXTRA_LD_POST}
In this case, the MP_EXTRA_LD_PRE is issued to the shell (before -Wl) and the MP_EXTRA_LD_POST is issued after. You need to pass valid options – see your language tool documentation. For the options to be included before the -Wl, you need a space as a separator:
MP_EXTRA_LD_PRE= -D_FOO -D_BAR
And for the options to be included after -Wl, you need a comma as a separator:
MP_EXTRA_LD_POST=--defsym=_FOO,--defsym=_BAR
If the toolchain does not support the use of a driver shell (like gcc), then simply use the _PRE variables.
Special Considerations for Each Language Tool
Besides the variables needed for each toolchain, you need to set:
- The tool locations (MP_CC, MP_AS, etc.)
- The directories where they are installed (MP_CC_DIR, MP_AS_DIR, etc.)
Macros used for each toolchain are described in the following sections.
MPLAB XC8 Toolchain
The required macro for the XC8 toolchain is:
- MP_PROCESSOR_OPTION - device name used by the compiler
The optional macros for the XC8 toolchain are:
- MP_EXTRA_CC_PRE
- MP_EXTRA_AS_PRE
- MP_EXTRA_AR_PRE (for lib projects)
- MP_EXTRA_LD_PRE (for a stand-alone project)
MPLAB XC16 Toolchain
The required macros for the MPLAB XC16 toolchain are:
- MP_PROCESSOR_OPTION
- MP_LINKER_FILE_OPTION
MP_LINKER_FILE_OPTION can be one of the two strings:
- ",—script=myScript24FJ256GB106.gld" – Use this string if the project contains a linker script, in this case named myScript24FJ256GB106.gld.
- ",-Tp24FJ256GB106.gld" – Use this string if the project does not contain a linker script. Use the name of the default linker script in the installation; in this case, p24FJ256GB106.gld. In Linux, the name of the .gld file is case-sensitive.
The optional macros for the MPLAB XC16 toolchain are:
- MP_EXTRA_CC_PRE
- MP_EXTRA_AS_PRE
- MP_EXTRA_AS_POST
- MP_EXTRA_AR_PRE (for lib projects)
- MP_EXTRA_AR_POST (for lib projects)
- MP_EXTRA_LD_PRE (for standalone projects)
- MP_EXTRA_LD_POST (for standalone projects)
MPLAB XC32 Toolchain
The required macros for the MPLAB XC32 toolchain are:
- MP_PROCESSOR_OPTION
- MP_LINKER_FILE_OPTION
MP_LINKER_FILE_OPTION can be one of the two strings:
- ",—script=myScript32X.gld" – Use this string if the project contains a linker script. In this case, it is named myScript32X.gld.
- "" – use the empty string if the project does not contain a linker script.
The optional macros for the MPLAB XC32 toolchain are:
- MP_EXTRA_CC_PRE
- MP_EXTRA_AS_PRE
- MP_EXTRA_AS_POST
- MP_EXTRA_AR_PRE (for lib project)
- MP_EXTRA_AR_POST (for lib project)
- MP_EXTRA_LD_PRE (for standalone projects)
- MP_EXTRA_LD_POST (for standalone projects)