7.3.1 Library Files

The compiler may include library files into the output per Figure 6-2.

By default, xc16-gcc will search known locations under the compiler installation directory for library files that are required during compilation.

Standard Libraries

The C standard libraries contain a standardized collection of functions, such as string, math and input/output routines. The range of these functions is described in the “16-Bit Language Tool Libraries” (DS51456).

User-Defined Libraries

You may create your own libraries. Libraries are useful for bundling and precompiling selected functions so that application file management is easier and application compilation times are shorter.

Libraries can be created manually using the compiler and the librarian. To create files that may then be used as input to the 16-bit librarian (xc16-ar), use the -c compiler option to stop compilation before the linker stage. For information on using the librarian, see the MPLAB^® XC16 Assembler, Linker and Utilities User’s Guide (DS50002106).

Libraries should be called liblibrary.a and can be added to the compiler command line by specifying its pathname (-Ldir) and -llibrary. For details on these options, see section Options for Linking.

A simple example of adding the library libmyfns.a to the command-line is:

xc16-gcc -mcpu=30f2010 -lmyfns example.c

Library files specified on the command line are scanned first for unresolved symbols, so these files may redefine anything that is defined in the C standard libraries.

User-Defined Libraries Development

When creating your own libraries, follow the guidelines listed below.

Library and Supporting Files

No library file should contain a main() function, nor settings for configuration bits or any other such data.

As with Standard C library functions, any functions contained in user-defined libraries should have a declaration added to a header file. It is common practice to create one or more header files that are packaged with the library file. These header files can then be included into source code when required.

OMF Libraries

MPLAB XC16 supports two object file formats, often called OMF for object module format. COFF is an older standard and is not recommend. ELF, combined with its debugging format DWARF, produces executables that contain a richer language for describing the artifacts of the executable program from a debugging perspective.

Should you wish to produce generic libraries that are COFF and ELF compatible, we recommend that each library be separated and named liblibrary-elf.a and liblibrary-coff.a. Each library, of course, should contain objects built for the appropriate OMF. Naming the libraries in this way will allow the linker to choose a correct library from the standard library inclusion option and the current OMF. In other words, -llibrary will match first against liblibrary.a followed by liblibrary-OMF.a. This makes it easier to switch between COFF and ELF.

Device Specific and Generic Libraries

If you would like to produce a library that will be compatible with a range of 16-bit devices, you may need to include more than one copy of each object file in the library. This is perfectly acceptable, as long as each copy has a unique name. The linker will reject object files that do not match the characteristics of the user selected device.

Consider a simple library that contains one file (and one function) name hello_world.c; you can guess at its use. The desire of this function is to work on a range of devices, for example: dsPIC30F6014, dsPIC33EP512MU810 and PIC24F16KA302. Compile hello_world.c once for each device and combine them into one library:

xc16-gcc -O1 -c hello_world.c -mcpu=30F6014 -o hello_world.30f.o
xc16-gcc -O1 -c hello_world.c -mcpu=33EP512MU810 -o hello_world.33ep.o
xc16-gcc -O1 -c hello_world.c -mcpu=24F16KA302 -o hello_world.24f.o
xc16-ar crv libhello_world-elf.a hello_world.30f.o hello_world.33ep.o hello_world.24f.o

This would produce a library that can be linked against any one of those devices.

xc16-gcc -O1 test.c -mcpu=30F6014 -o test.exe -L. -lhello_world

If a library is required to link against any device, the use of a set of generic device names, listed in Readme_XC16.html or acquired directly from the tool using the compiler option -mprint-devices, will produce object files that will link against any device.