How to test an MPLAB® X Library

Create a new project

When you create a library, you will need to test it in a standalone project. The easiest way to do this is to create a test project that is open at the same time as the library project in MPLAB^® X. This makes it very easy to switch back and forth as you make changes to the library and then test those changes. So, without closing the library project, create a new project to test the library:

Choose Project Type

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

Specify Project Parameters

For all intents and purposes, this is just an ordinary standalone project. So, simply create the project as you normally would by completing the steps of the project wizard. For this example, the following parameters were used:

• Family: PIC24
• Device: PIC24FJ128GA010 (other PIC24F devices should work too)
• Debug Header: Only check the box if you are using one.
• Tool: Choose a simulator unless you have a hardware debug tool (i.e. MPLAB ICD 3, REAL ICE™, etc.) and appropriate target hardware.
• Compiler: Choose the C30 compiler.
• Project Name: MyLibTest
• Project Location: Same location as MyLib (i.e. MyLib.X's parent directory).

Add Files

1. Right click on Header Files and select New > Empty File… from the pop-up menu. Name the file MyLib.h.
2. Right click on Source Files and select New > Empty File… from the pop-up menu. Name the file main.c.
3. Right click on Library Files and select Add Existing Item… In the file dialog that pops up, navigate to and select your library file from the MyLib project. In this example, it is at: ..\MyLib.X\dist\default\mylib.x.a (go to wherever your MyLib.X folder was created from the library project above).

By adding the library file from the location where it is generated by the MyLib project, we can switch back and forth between these projects to tweak the library very easily. Every time the MyLib project is built, a new mylib.x.a is generated. Because the MyLibTest project references this file's location, MyLibTest will always have the latest build of mylib.x.a.

If this weren't a test project, it would be better to copy the mylib.x.a file into this project's directory. Then add the copy in this project's directory to the project tree instead. Once the library is tested, there is no need to always reference the original project. All you need is a copy of mylib.x.a and the header file MyLib.h that we are about to write.

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

Add Code

Add the following code to their respective files in your project:

MyLib.h

main.c

The first line of main.c, #include "MyLib.h", and the file it references are critical. Without these, the compiler will not recognize add() and sub() as valid functions. Remember, the library contains pre-compiled code, so the compiler doesn't know anything about it. This header file is essentially telling the compiler, "you will see this program make calls to add() and sub() which aren't implemented here. All you need to do is generate the appropriate parameter passing code based on the template of these function prototypes. The linker will be made aware of where to find the implementations of these functions so that it can make the appropriate connections between these function calls and their implementations."

If this project only made a call to one of the functions, only the code that implemented that function would be added to the HEX file. It works this way because all of the functions in the library were implemented in their own source files. If the library code were implemented as a single source file, then a call to just one function would result in the code for all of the functions being added to the HEX file.

Build Project

Make sure that you have selected the MyLibTest project by clicking on it in the project tree. Then click the Debug Project button  on the toolbar to build the project and run it in the debugger you selected in step 2.

View Output

1. Halt the program by clicking on the Pause button  on the toolbar.
2. Open a Watches window by selecting from the menu: Window > Debugging > Watches.
3. Add the two result variables sum and difference to the Watches window (highlight one in the editor, then click and drag it to the watches window).

You should see the following results as shown in the screenshot at left:

Clearly, the library worked right the first time. However, if changes are required all you would have to do is:

1. End the current debug session by clicking on the Finish Debugger Session button () on the toolbar.
2. Change the library code as needed.
3. Click on the MyLib project to ensure it is selected, then build it ().
4. Click on the MyLibTest project to ensure it is selected and debug it again ().

You don't need to remove the old mylib.x.a from MyLibTest and then add the new one after it was rebuilt because MyLibTest has a reference that points to the mylib.x.a file generated by the MyLib project. So, whenever MyLib is rebuilt, MyLibTest automatically incorporates the rebuilt mylib.x.a. So, when you rebuild MyLibTest, it uses the newly built mylib.x.a.

Once you are satisfied that your library works, you can add the library file (e.g. mylib.x.a) to any project that uses the same processor family and includes the header file (e.g., MyLib.h) in any source file that calls one of the library's functions. You do not need to have the library project open nor do you need to provide the library's source code to its users. The library file and header file are all that is needed to take advantage of all the code in the library.