Creating Libraries in MPLAB ®X IDE

Last modified by Microchip on 2023/11/10 11:04

How to create a library

There are two main parts of a library:

  1. The library project
  2. The header file that you will provide to those who will use the pre-compiled library in their own projects

Example Library Project

Launch the new project wizard

Toolbar:Main_New_Project.png
 
Keyboard:Ctrl+Shift+N
  
Menu:File > New Project…

Back to top


 Choose Project Type

Choose Library Project from the list on the right and click Next >.

This will create a project that will generate a library file (*.lib or *.a depending on which compiler you use) instead of a hex file. This project will not be able to run on its own as it will not have a main() function. The resulting library will be used in another project that has its own main() function.

dialog window for choosing a project type

Back to top


 Select Device

Select the device family and device that are in the same family for which you wish to use this library. Click Next >.

As a general rule, libraries may be used on any device that shares the architecture of its original target. In this example, we are choosing a PIC24FJ128GA010 because it is a fairly generic "superset" device that has a little bit of everything that the PIC24F family has to offer. This doesn't mean that we can only use this library with this device. On the contrary, we should be able to use it with any PIC24F device as long as we don't use some feature that is unique to the PIC24FJ128GA010. The key is that if our library references any on chip hardware by its register names, this library may only be used with devices whose registers share the same names. The reason this works is because this library project will not be linked. So, register names will NOT be equated to their hardware addresses. Rather they are left "floating" until this library is used in a different, standalone project where the linker will finally connect the names used here to the hardware addresses of the standalone project's target device.

My Lib

Back to top


Select Header

Leave this checkbox unchecked. This only affects debugging, which cannot be done directly with a library project.

Click Next >.

Select Header window

Back to top


Select Tool

Since a library project cannot be debugged on its own, choose nothing or choose the simulator. It really doesn't matter.

Click Next >.

Select tool window

Back to top


Select Compiler

Choose the appropriate compiler or assembler for your target architecture.

Click Next >.

The choice of compiler here not only determines which tool will build the object files for the library, but also determines which compiler this library may be used with when included in other projects. However, you are not tied down to a particular version number in most circumstances. For example, if I choose the XC16 compiler, I cannot use this library with Hi-Tech, CCS, nor any other compiler that supports this device family, but I should be able to use it with subsequent versions of the XC16 compiler.

Libraries may also be written in and used in assembly language, but they must be written as relocatable code. If you wish to mix assembly and C, then assembly libraries must be written to be both relocatable and C callable. This requires a thorough understanding of your compiler's parameter passing conventions.

select compiler window

Back to top


 Select Project Name and Folder 

Choose a name and location for your project. Click Finish.

The name you give your project will be the name of the library file it generates. In this example the project name is MyLib and the library file it generates will be MyLib.x.a. The ".a" suffix is the library suffix used by XC16 and XC32. The ".x" is automatically inserted to indicate that this library was built using the MPLAB® X IDE. The name isn't critical and you can always change the name of the generated library file in your file manager before using it in another project.

select project window

Click image to enlarge

XC8: Recent versions of MPLAB® X IDE now allow you to create library projects for the MPLAB XC8 Compiler. The process of creating and building a library project for this compiler is the same as that for the other MPLAB XC compilers, with a few minor changes to the library naming conventions. Please read the "Building XC8 Libraries" page in order to understand these differences.

Back to top


 Add Source Files 

To add blank source files to the project, right click on the Source Files folder of the project tree and select New > Empty File… from the pop-up menu. This will prompt you to provide a filename and location for the files. Do this twice to create two new source files named add.c and sub.c. In both cases, keep the default location, which is inside the project directory.

Each of these files will contain a single function. When the project is compiled, the library will contain two object files, add.o and sub.o. Putting each function into a separate file will make the library more efficient for you. If your code only uses the function inside add.o, then only the code from add.o will be compiled into the HEX file. This means you can create huge libraries of related functions, but only the code from the functions that are actually used will be compiled into the HEX file, so memory will not be wasted on code that never gets called.

Project file list after the two source file are added

Once you have added the source files, your project will look like following image.

project window after process is complete

add source file window

Back to top


 Add Code 

Add the following code to the appropriate source files in your project:

add.c

// This function takes two parameters, adds them together and returns the result
int add(int a, int b)
{
   return (a + b);
}

sub.c

// This function takes two parameters, subtracts the second from the first and returns the result
int sub(int a, int b)
{
   return (a - b);
}

Back to top


 Build the Library 

Once you have added all the code to the sources files, the project is ready to be built. Click on the Build button Main_Build_Project.png on the toolbar.

files window for the project

If the build was successful, click on the Files tab in the Project window and navigate down the tree to MyLib > dist > default. You should see your library file mylib.x.a here. This is the file you will include in other projects.

project window showing newly built librayfile

Click image to enlarge

Back to top


Example Library Header File

The header file is not used in the library itself, but in any project that will use the library. This is a file you must create to expose the functions in your library that you want to make available to your library's users. An example of a function you might not want to make available via the header file is one that is itself called by one of the library's functions, but you don't want the end-user of the library to call directly. In the simple library we created above, there are only two functions available, so our header file will have two function prototypes. The function prototype is nothing more than the function header (first line) of each function in the library terminated with a semicolon. Although not required, it is customary to give the header file the same name as the library file. Since our library is called MyLib.x.a, we will call the header MyLib.h (or MyLib.x.h if you prefer).

MyLib.h

int add(int a, int b);
int sub(int a, int b);

Your library's users must include this header file (for example, #include "MyLib.h") in every file of their project where they make calls to one of the library's functions.

Back to top