Example of a Makefile Project

This example shows how to create a user makefile project in MPLAB X IDE that will run either a batch file or make on user code that was created outside of the IDE. The user code consists of a single file t.c. The simple code contained in this file is listed below.

Example: t.c Code

#include <xc.h>
int main(void) {
while(1) {
}
return 0;
}

For production the code is linked into t_production.hex and for debug the code is linked into t_debug.elf.

For this example, t.c, the batch file makeme.bat and the user makefile Makefile are assumed to be in the (Windows OS) directory:

C:\Users\MCHP\MPLABXProjects\makestuff\myOwnCodeWithItsOwnMakefile

Substitute your UserName for MCHP to recreate the example on your PC.

User Makefile Project – Create Code from a Batch File
User Makefile Project – Create Code from User Makefile
User Makefile Project – Complete
User Makefile Project – Parse Macros

User Makefile Project – Create Code from a Batch File

To compile the code, the simple batch file makeme.bat takes as arguments production, debug or clean. If production is passed then t_production.hex is built. If debug is passed then t_debug.elf is built. If clean is passed, then the .elf and .hex files are erased.

Example: makeme.bat Code

::assumes xc32-gcc and xc32-bin2hex are on the path
rem @echo off
set COMPILER=xc32-gcc
set BIN2HEX=xc32-bin2hex
set PROCESSOR=32MX360F512L
if "%1" == "production" goto production
if "%1" == "clean" goto clean
:debug
%COMPILER% -mprocessor=%PROCESSOR% -g -D_DEBUG -o t_debug.elf t.c
goto end
:production
%COMPILER%  -mprocessor=%PROCESSOR% -o t_production.elf t.c
%BIN2HEX% t_production.elf
goto end
:clean
del /F *.elf
del /F *.hex
goto end
:end

To create a new user makefile project in MPLAB X IDE, follow the steps in New Project - User Makefile:

1.Choose Project: Select “Microchip Embedded,” “User Makefile Project.”
2.Select Device: Select PIC32MX360F512L as the device.
3.Select Header: None available for this device.
4.Select Tool: Select the hardware tool by SN or the Simulator. For this example, the Simulator was used.
5.Select Plugin Board: None used for this example.
6.Select Project Name and Folder: For this example, the Project Folder will be a sibling to myOwnCodeWithItsOwnMakefile. Therefore the Project Location will be: C:\Users\MCHP\MPLABXProjects\makestuff. The Project Name is MPLABXProjectT.
Figure 1. User Makefile Project – Select Project Nane and Folder
7.Create User Makefile Project: Enter information to set up your makefile project.
The Working Directory is where the batch file build, debug build and clean commands will be run. This directory could be set as the absolute path:

C:\Users\MCHP\MPLABXProjects\makestuff\myOwnCodeWithItsOwnMakefile.

Doing this, however, makes the MPLAB X IDE project less portable. Therefore the Working Directory, Image name and the Debug image name will be entered as relative paths with respect to the MPLAB X IDE project directory.

Click Finish to create the project.

Figure 2. User Makefile Project – Create from Batch

User Makefile Project – Create Code from User Makefile

To compile the code, the simple user makefile Makefile takes as arguments production, debug or clean. If production is passed then t_production.hex is built. If debug is passed then t_debug.elf is built. If clean is passed then the .elf and .hex files are erased.

Example: User Makefile Code

# Assumes xc32gcc and xc32bin2hex are on the path
COMPILER=xc32gcc
BIN2HEX=xc32bin2hex
PROCESSOR=32MX795F512L
production: t_production.hex
debug: t_debug.elf
t_debug.elf: t.c
$(COMPILER) mprocessor=$(PROCESSOR) -g -D_DEBUG -o t_debug.elf
t.c
t_production.hex: t_production.elf
$(BIN2HEX) t_production.elf
t_production.elf: t.c
$(COMPILER) mprocessor=$(PROCESSOR) o t_production.elf t.c
clean:
del /F *.hex
del /F *.elf

To create a new user makefile project in MPLAB X IDE, follow steps 1-6 from “User Makefile Project – Create Code From a Batch File”. For Step 7, set up as per figure below.

The Working Directory is where the user Makefile build, debug build and clean commands will be run. The Working Directory, Image name and the Debug image name are entered as relative paths with respect to the MPLAB X IDE project directory.

MPLAB X IDE uses GNU Make to build, debug build and clean. As per “User Makefile Project Folder and Working Folder”, MPLAB X IDE will run the Makefile in the project folder, which will change directories to the working folder. There, make will look for a makefile and find the user-defined Makefile, which will define how to build, debug build, and clean.

Note: Another way to define commands, for example the Build command, would be to use the -f option to specify the user makefile, as in:  make -f Makefile production.

Click Finish to create the project.

Figure 3. User Makefile Project – Create from Makefile

User Makefile Project – Complete

Once the project has been created, you should see the following in the Projects window. You can right click on the project name to build the project.

Figure 4. User Makefile Project – Project Tree

If you wish to change settings, right click on the project name and select “Properties.”

Figure 5. User Makefile Project – Project Properties

For this example, the results of build (t_production.hex) and debug build (t_debug.elf) are found in the myOwnCodeWithItsOwnMakefile working directory. As only the MPLABXProjectT project directory is visible in MPLAB X IDE, you will not see any changes in the IDE Projects window after a build.

User Makefile Project – Parse Macros

You can parse and add macros for MPLAB XC C compilers to your makefile project. To do this you need to call the compiler on the command line with the relevant arguments and copy the whole output to the first panel of the “Parse macros” dialog.

To run the compiler on the command line, you will need a C file. For this example, use the code below and paste into a file named xcmain.c:

#include <xc.h>
void main(void) {
return;
}

Ensure that your computer knows the Path to your MPLAB XC compiler. Then execute the following on the command line:

xc32-gcc -dM -E xcmain.c > macros32.txt

The MPLAB XC32 C compiler is used, not the MPLAB XC32++, so xc32-gcc is the executable. The option -dM tells the preprocessor to output only a list of the macro definitions that are in effect at the end of preprocessing. The option -E stops execution after the preprocessing stage. The redirect (>) character sends the output into the file macros.txt.

For other MPLAB XC C compilers, you can use:

xc16-gcc -dM -E xcmain.c > macros16.txt
xc8 --pre -v --chip=8BitMCU xcmain.c > macros8.txt

where 8BitMCU should be replaced with your 8-bit device. The macros8.txt file will also require additional editing to isolate the macros from other text in the file.

To open the “Parse macros” dialog:

1.Right click on the project name and select “Properties.”
2.Under “Categories,” select “Makefile.”
3.Under “Set User Makefile properties,” go to “User Macros” and click on the Parse button.

To parse the macros:

1.Copy and paste the contents of macros.txt into the dialog left panel.
2.Check the checkbox for your MPLAB XC C compiler, in this case “xc32.”
3.Click the Parse button.

Click a button to Replace the current contents of the User Macros text box, Append to existing text in the text box, or Cancel to leave the existing text unchanged.

Figure 6. Parse Macros Dialog