How to Compile MPLABX Projects from the Command Line

Within the past couple of years, Microchip has released MPLABX, a Netbeans based IDE for their microcontrollers. The IDE works great and makes it easy to develop and build your projects; however, building releases locally on developer machines is not the ideal way to be releasing software. Continuous Integration (CI) and build servers solve this problem and are in widespread use by the software industry, but I am surprised that I don’t see more embedded developers using them.

I suspect that one of the contributing factors for this is that setting up embedded toolchains can be complicated and time consuming. IDEs do a good job of making this easy, but build servers usually require building the projects through scripts and the command line. I’ve seen a lot of people asking questions about how to build their MPLABX projects through the command line, presumably so that they can set up automated build servers for their projects. The process is really quite simple once you understand the how MPLABX builds a release.

1. Generate a Makefile based on the build configuration and settings of your project.
2. Run the build using that new Makefile.

With the earlier releases of MPLABX there was actually no way of building the Makefile without firing up the GUI. I’m not sure in what version they added it, but I know that at least as of version 2.20 a command line utility has been added to generate the Makefile.

Setting up the Environment

1. Make sure you have a recent enough version of MPLABX. Look inside your MPLABX installation folder and browse to mplab_ide\bin. If you see a file called prjMakefilesGenerator.bat then move on to the next step. Otherwise, update your copy of MPLABX.
2. Add the folder containing  prjMakefilesGenerator.bat to PATH. This will allow you to run the Makefile generator simply by typing its name on the command line. On Windows, the directory you will need to add to PATH will most likely be C:\Program Files (x86)\Microchip\MPLABX\mplab_ide\bin.
3. Add the MPLABX utilities required to run a Makefile to PATH. The utilities are located inside the MPLABX installation folder inside of gnuBins\GnuWin32\bin. This will allow you to run the Makefile simply by using the command make . On Windows the directory you will need to add to PATH will most likely be C:\Program Files (x86)\Microchip\MPLABX\gnuBins\GnuWin32\bin. Make sure that you don’t have any other make commands on your path or this will cause problems.

Building the Project

1. Open up a command line and browse to the project’s root folder.
2. Run the prjMakefilesGenerator.bat to generate the Makefile: prjMakefilesGenerator.bat <full path to project folder>.The Makefile should now appear in the project’s root directory. If you are going to be building on a build server, you won’t always know what the full path is. On a Windows build machine, you could use the following command instead: prjMakefilesGenerator.bat %CD%. This will automatically insert the path of the current directory when you run the command.
3. Find out what the build command is by running the GUI version of MPLABX. Open the project you are trying to build and run the “Clean and Build” command. Then look in the Output window (If you don’t see it, try Windows > Output > Output) to see the command that was run. Look for the first command starting with make . The command should look something like this: make -f nbproject/Makefile-buildconfigname.mk SUBPROJECTS= .build-conf. You can replace buildconfigname from the line above with whatever build configuration you want to build.