In this post, I will explain how to add a custom template to MPLab-X IDE, the Integrated Development Environment from Microchip.

Why?

That is a good question. For me, the main reason is that, by some awkward reason, the installation of MPLab-X IDE leaves us with code templates that are not correct or not the best option.

The standard main C file template provided by MPLab-X installation for a C main file is the following:

/* 
 * File heading stuff; not relevant for now
 */

#include <stdio.h>
#include <stdlib.h>

/*
 * 
 */
int main(int argc, char** argv) {

    return (EXIT_SUCCESS);
}

This template would be OK for a general purpose C program, but not for an embedded project, designed to run on an PIC micro-controller based system, because:

  • It does not include xc.h, which is the header file that allows code in the source file to access compiler- or device-specific features (see section 1.2 of “MPLAB® XC32 User’s Guide for Embedded Engineers”). Including xc.h allows the code to be compiled for different target micro-controllers, as the compiler, based on the selected device, will set macros that allow xc.h to vector to the correct device-specific header file. The Manual states that one should “not include a device-specific header in your code or your code will not be portable.”
  • It does not include other header files that are (in my opinion) mandatory for embedded systems, such as stdint.h-
  • Including argc and argv as arguments to main() seems to me of little use (although it may make sense in some occasions, it is not the general case for embedded software).

As such, one would like to start our projects with something like:

#include <xc.h>
#include <stdint.h>

int main(void) {

    /* Code goes here */

}

which we would like to be the result of including the template to start writing our code.

Templates in MPLab-X

When starting a new project, you can add a new file which is created from an existing template. When you choose the option “New File (Ctrl-N)” in the IDE, you get the following dialog, where you can choose one of the available templates (in this case, .c or .h files for a C program).

new-file_dialog_with_templates_std

Choosing the standard “C Main File” results in the code shown above for the standard template.

Adding a new template

We now would like to have the possibility of adding a new template, with our starting point for coding. For example, one might want template code to be:

/**
 * \file:   %<%NAME%>%.%<%EXTENSION%>%
 * \author: %<%USER%>%
 *
 * \date %<%DATE%>%, %<%TIME%>%
 */

#include <xc.h>
#include <stdint.h>

int main(void){
    
    /* Code goes here */
    
}

This code contains the code presented before for the desired template and a few extras in the heading comments:

  • The tokens \file, \author and \date are Doxygen commands. Doxygen is a tool for generating documentation from annotated source code.
  • The tokens with %<%...%>% are variables that are replaced by their value when the new file is created from the template.

Create the new template

To create a new template, start by creating a file with the contents you want for the template. The code above is available in the siemain.c file, that you can download.

Add your template to MPLab-X IDE templates

To add your template to MPLab-X IDE templates, select Tools->Templates from the main menu: tool-templates

The “Template Manager” window opens and you will see the installed templates: Template Manager window

Select the section with C templates and click “Add” to add your template. Then browse and select the file with the template. The file will now appear in the list of C templates. Right-clicking over the file name allows you to rename the template (you can give a more descriptive name, rather than the original file name) and edit its properties.

Add new template

To finish, edit the template properties and make sure that the property “Template Categories” is set to c-types.

Add new template

Using the template

To use the template, just select the “New File” option, and choose the C templates section. The new template should appear:

new-file dialog with new template

Select the template and a new C main file will be created.

new-file created

Resources:

Template file samples

In the following links, you can find a set of template files that you can add to a MPLab-X IDE installation.

  • siemain.c: simple template example for the main file of a project.
  • siemodule.c, siemodule.h: templates (code .c and header .h) for a C module. The template for the C code file contains a line to #include the header file with the same basename. Only the header file contains comments for creating Doxygen documentation.