8.1.1 Using the Archiver/Librarian

The archiver program is called xc8-ar and is used to create and edit library archive files. It has the following basic command format:

xc8-ar [options] file.a [file.p1 file.o ...]

where file.a represents the library archive being created or edited.

The files following the archive file, if required, are the modules that are required by the command specified and may be either p-code (.p1) or object (.o) modules. P-code modules must be used for content built from C source; object modules must be used for content built from assembly source.

The options is zero or more options, tabulated below, that control the program.

Table 8-1. Archiver Command-line Options
Option	Effect
`-d modules`	Delete module
`-m modules`	Re-order modules
`-p`	List modules
`-r modules`	Replace modules
`-t`	List modules with symbols
`-x modules`	Extract modules
`--target device`	Specify target device

When replacing or extracting modules, the names of the modules to be replaced or extracted must be specified. If no names are supplied, all the modules in the archive will be replaced or extracted respectively.

Creating an archive file or adding a file to an existing archive is performed by requesting the archiver to replace the module in the archive. Since the module is not present, it will be appended to the archive.

Object (.o extension) and p-code (.p1 extension) modules can be added to the same archive.

The archiver creates library archives with the modules in the order in which they were given on the command line. When updating an archive, the order of the modules is preserved. Any modules added to an archive will be appended to the end.

The ordering of the modules in an archive is significant to the linker. If an archive contains a module that references a symbol defined in another module in the same archive, the module defining the symbol should come after the module referencing the symbol.

When using the -d option, the specified modules will be deleted from the archive. In this instance, it is an error not to supply any module names.

The -p option will list the modules within the archive file.

The -m option takes a list of module names and re-orders the matching modules in the archive file so that they have the same order as the one listed on the command line. Modules that are not listed are left in their existing order, and will appear after the re-ordered modules.