Creating Makefiles Outside of the MPLAB® X IDE

Last modified by Microchip on 2023/11/09 09:12

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.

Note: The safest way to have the Makefiles match the values of the project in the IDE is to either regenerate them with the IDE itself or to use the prjMakefilesGenerator utility, explained later. The IDE will recreate the Makefiles for the main configuration in a project when the project is open. However, you might benefit from some other customization steps that modify the Makefiles' behavior once the Makefiles are already created. This page explains those other steps.


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.

Back to top


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

1
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
prjMakefilesGenerator [-help] [-v] [-f] [-mplabx-userdir=<path>] [-create] [-delete] [-setoptions=@<argfile>] [project_path[@config_name]*]+
        <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.

Terminal widow showing the path

Back to top


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.

Back to top


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.

Back to top

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:

  1.  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
  2.  Install the X tools which will install the make in /usr/bin/make.

Back to top

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.

Back to top


Makefile Interface

To remove all target files for a given configuration:

  1. Change the directory to $PROJECT_DIR.
  2. 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:

  1. Change directory to $PROJECT_DIR.
  2. make clobber

To run the Makefile for a given configuration:

  1. Change directory to $PROJECT_DIR.
  2. Set environment variables to override values in the Make process.
  3. 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 

Back to top


Environment Variables to Control the Make Process

There are four ways to set the variables that control the Make process:

  1. Use environmental variables, and call Make with the -e option:
    $ export MP_CC=/opt/microchip/xc16/v1.21/bin/xc16-gcc
    $ make -e
  2. Set the variables in the command line when calling Make. For example:
    $ make MP_CC=/opt/microchip/xc16/v1.21/bin/xc16-gcc
  3. Create a nbproject/Makefile-local-$conf.mk for the machine in use. Include the values of the environmental variables in it.
  4. 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.

Back to top


Variables to Control Tool Names/Locations

The following variables can be overridden:

MP_CCComplete path to C compiler executable name
MP_BCComplete path to Basic compiler executable name
MP_ASComplete path to assembler executable name
MP_LDComplete path to linker executable name
MP_ARComplete path to archiver executable name
MP_CC_DIRDirectory to C compiler executable
MP_BC_DIRDirectory to basic compiler executable
MP_AS_DIRDirectory to assembler compiler executable
MP_LD_DIRDirectory to linker compiler executable
MP_AR_DIRDirectory to archiver compiler executable
# Example *nix:
make MP_CC=/opt/microchip/mplabc30/v3.24/bin/pic30-gcc
# Example Windows:
make "C:/Program\ Files/Microchip/xc16/bin/xc16-gcc.exe"

Back to top


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 generated Makefiles for the MPLAB XC C compilers cannot be used with different processors by simply changing the value of MP_PROCESSOR_OPTION. This is only for the debug images. You can still produce different HEX files for different devices by changing the MP_PROCESSOR_OPTION value.

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.

ToolchainFirst version supported.
All versions greater or equal to
this version issue -mreserve
XC81.00
XC161.21
XC321.30

Back to top


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.

Back to top


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_PREMP_EXTRA_CC_POST
MP_EXTRA_BC_PREMP_EXTRA_BC_POST
MP_EXTRA_AS_PREMP_EXTRA_AS_POST
MP_EXTRA_AR_PREMP_EXTRA_AR_POST
MP_EXTRA_LD_PREMP_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.

Back to top


Special Considerations for Each Language Tool

Besides the variables needed for each toolchain, you need to set:

  • The tool locations (MP_CCMP_AS, etc.)
  • The directories where they are installed (MP_CC_DIRMP_AS_DIR, etc.)

Macros used for each toolchain are described in the following sections.

Back to top


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)

Back to top


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:

  1. ",—script=myScript24FJ256GB106.gld" – Use this string if the project contains a linker script, in this case named myScript24FJ256GB106.gld.
  2. ",-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)

Back to top


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:

  1. ",—script=myScript32X.gld" – Use this string if the project contains a linker script. In this case, it is named myScript32X.gld.
  2. "" – 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)

Back to top