6.3.1 Library Files

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 MPLAB® XC-DSC Language Tools Libraries Reference Manual (DS-50003591).

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 DSC librarian (xc-dsc-ar), use the -c compiler option to stop compilation before the linker stage. For information on using the librarian, see the “MPLAB® XC-DSC Assembler, Linker and Utilities User’s Guide” (DS-50003590).

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 6.6.9 Options for Linking.

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

xc-dsc-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.

ELF Libraries

MPLAB XC-DSC supports the object module format of ELF. ELF, combined with its debugging format DWARF, produces executables that contain a rich language for describing the artifacts of the executable program from a debugging perspective

Should you wish to produce generic libraries that are ELF compatible, we recommend that each library be named liblibrary-elf.a. Naming the libraries in this way will allow the linker to choose a correct library from the standard library inclusion option. In other words, -llibrary will match first against liblibrary.a followed by liblibrary-elf.a.

Device Specific and Generic Libraries

If you would like to produce a library that will be compatible with a range of DSC 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 dsPIC33EV256GM106. Compile hello_world.c once for each device and combine them into one library:

xc-dsc-gcc -O1 -c hello_world.c -mcpu=30F6014 -o hello_world.30f.o
xc-dsc-gcc -O1 -c hello_world.c -mcpu=33EP512MU810 -o hello_world.33ep.o
xc-dsc-gcc -O1 -c hello_world.c -mcpu=33EV256GM106 -o hello_world.33ev.o
xc-dsc-ar crv libhello_world-elf.a hello_world.30f.o hello_world.33ep.o hello_world.33ev.o

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

xc-dsc-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_XC-DSC.html or acquired directly from the tool using the compiler option -mprint-devices, will produce object files that will link against any device.