7 Archiver Description

The ARM archiver lets you combine several individual files into a single archive file. For example, you can collect several macros into a macro library. The assembler searches the library and uses the members that are called as macros by the source file. You can also use the archiver to collect a group of object files into an object library. The linker includes in the library the members that resolve external references during the link. The archiver allows you to modify a library by deleting, replacing, extracting, or adding members.

On architectures like ARM, it is often desirable to have multiple versions of the same object file libraries, each built with different sets of build options. When several versions of a single library are available, the library information archiver can be used to create an index library of all the object file library versions. This index library is the used in the link step in place of a particular version of your object file library.

7.1 Archiver Overview

You can build libraries from any type of files. Both the assembler and the linker accept archive libraries as input; the assembler can use libraries that contain individual source files, and the linker can use libraries that contain individual object files.

One of the most useful applications of the archiver is building libraries of object modules. For example, you can write several arithmetic routines, assemble them, and use the archiver to collect the object files into a single, logical group. You can then specify the object library as linker input. The linker searches the library and includes members that resolve external references.

You can also use the archiver to build macro libraries. You can create several source files, each of which contains a single macro, and use the archiver to collect these macros into a single, functional group. You can use the .mlib directive during assembly to specify that macro library to be searched for the macros that you call. Section 6 discusses macros and macro libraries in detail, while this chapter explains how to use the archiver to build libraries.

7.2 The Archiver's Role in the Software Development Flow

Figure 7-1 shows the archiver's role in the software development process. The shaded portion highlights the most common archiver development path. Both the assembler and the linker accept libraries as input.

Figure 7-1 The Archiver in the ARM Software Development Flow

7.3 Invoking the Archiver

To invoke the archiver, enter:

armar[-]command [options] libname [filename₁ ... filename_n ]

armar	is the command that invokes the archiver.
[-]command	tells the archiver how to manipulate the existing library members and any specified. A command can be preceded by an optional hyphen. You must use one of the following commands when you invoke the archiver, but you can use only one command per invocation. The archiver commands are as follows:
	@	uses the contents of the specified file instead of command line entries. You can use this command to avoid limitations on command line length imposed by the host operating system. Use a ; at the beginning of a line in the command file to include comments. (See Example 7-1 for an example using an archiver command file.)
	a	adds the specified files to the library. This command does not replace an existing member that has the same name as an added file; it simply appends new members to the end of the archive.
	d	deletes the specified members from the library.
	r	replaces the specified members in the library. If you do not specify filenames, the archiver replaces the library members with files of the same name in the current directory. If the specified file is not found in the library, the archiver adds it instead of replacing it.
	t	prints a table of contents of the library. If you specify filenames, only those files are listed. If you do not specify any filenames, the archiver lists all the members in the specified library.
	x	extracts the specified files. If you do not specify member names, the archiver extracts all library members. When the archiver extracts a member, it simply copies the member into the current directory; it does not remove it from the library.
options	In addition to one of the commands, you can specify options. To use options, combine them with a command; for example, to use the a command and the s option, enter -as or as. The hyphen is optional for archiver options only. These are the archiver options:
	-q	(quiet) suppresses the banner and status messages.
	-s	prints a list of the global symbols that are defined in the library. (This option is valid only with the a, r, and d commands.)
	-u	replaces library members only if the replacement has a more recent modification date. You must use the r command with the -u option to specify which members to replace.
	-v	(verbose) provides a file-by-file description of the creation of a new library from an old library and its members.
libname	names the archive library to be built or modified. If you do not specify an extension for libname, the archiver uses the default extension .lib.
filenames	names individual files to be manipulated. These files can be existing library members or new files to be added to the library. When you enter a filename, you must enter a complete filename including extension, if applicable.

NOTE

Naming Library Members

It is possible (but not desirable) for a library to contain several members with the same name. If you attempt to delete, replace, or extract a member whose name is the same as another library member, the archiver deletes, replaces, or extracts the first library member with that name.

7.4 Archiver Examples

The following are examples of typical archiver operations:

If you want to create a library called function.lib that contains the files sine.obj, cos.obj, and flt.obj, enter:


                                         armar -a function sine.obj cos.obj flt.obj

The archiver responds as follows:

==> new archive 'function.lib' ==> building new archive 'function.lib'

You can print a table of contents of function.lib with the -t command, enter:


                                         armar -t function

The archiver responds as follows:

             FILE NAME SIZE DATE
 ---------------- ----- ------------------------
 sine.obj 300 Wed Jun 15 10:00:24 2011
 cos.obj 300 Wed Jun 15 10:00:30 2011
 flt.obj 300 Wed Jun 15 09:59:56 2011

If you want to add new members to the library, enter:


                                         armar -as function atan.obj

The archiver responds as follows:

      ==> symbol defined: '_sin'
 ==> symbol defined: '$sin'
 ==> symbol defined: '_cos'
 ==> symbol defined: '$cos'
 ==> symbol defined: '_tan'
 ==> symbol defined: '$tan'
 ==> symbol defined: '_atan
 ==> symbol defined: '$atan'
 ==> building archive 'function.lib'

Because this example does not specify an extension for the libname, the archiver adds the files to the library called function.lib. If function.lib does not exist, the archiver creates it. (The -s option tells the archiver to list the global symbols that are defined in the library.)

If you want to modify a library member, you can extract it, edit it, and replace it. In this example, assume there is a library named macros.lib that contains the members push.asm, pop.asm, and swap.asm.


                                        armar -x macros push.asm

The archiver makes a copy of push.asm and places it in the current directory; it does not remove push.asm from the library. Now you can edit the extracted file. To replace the copy of push.asm in the library with the edited copy, enter:


                                        armar -r macros push.asm

If you want to use a command file, specify the command filename after the -@ command. For example:


                                        armar -@modules.cmd

The archiver responds as follows:

==> building archive 'modules.lib'

Example 7-1 is the modules.cmd command file. The r command specifies that the filenames given in the command file replace files of the same name in the modules.lib library. The -u option specifies that these files are replaced only when the current file has a more recent revision date than the file that is in the library.

Example 7-1 Archiver Command File

; Command file to replace members of the
; modules library with updated files
; Use r command and u option:
ru
; Specify library name:
modules.lib
; List filenames to be replaced if updated:
align.asm
bss.asm
data.asm
text.asm
sect.asm
clink.asm
copy.asm
double.asm
drnolist.asm
emsg.asm
end.asm

7.5 Library Information Archiver Description

Section 7.1 explains how to use the archiver to create libraries of object files for use in the linker of one or more applications. You can have multiple versions of the same object file libraries, each built with different sets of build options. For example, you might have different versions of your object file library for big and little endian, for different architecture revisions, or for different ABIs depending on the typical build environments of client applications. However, if you have several versions of a library, it can be cumbersome to keep track of which version of the library needs to be linked in for a particular application.

When several versions of a single library are available, the library information archiver can be used to create an index library of all of the object file library versions. This index library is used in the linker in place of a particular version of your object file library. The linker looks at the build options of the application being linked, and uses the specified index library to determine which version of your object file library to include in the linker. If one or more compatible libraries were found in the index library, the most suitable compatible library is linked in for your application.

7.5.1 Invoking the Library Information Archiver

To invoke the library information archiver, enter:

armlibinfo [options] -o=libname libname₁ [libname₂ ... libname_n ]

armlibinfo	is the command that invokes the library information archiver.
options	changes the default behavior of the library information archiver. These options are:
	-olibname	specifies the name of the index library to create or update. This option is required.
	-u	updates any existing information in the index library specified with the -o option instead of creating a new index.
libnames	names individual object file libraries to be manipulated. When you enter a libname, you must enter a complete filename including extension, if applicable.

7.5.2 Library Information Archiver Example

Consider these object file libraries that all have the same members, but are built with different build options:

Object File Library Name	Build Options
mylib_ARMv4_be.lib	--code_state=32 --silicon_version=4 --endian=big
mylib_ARMv4_le.lib	--code_state=32 --silicon_version=4 --endian=little
mylib_THUMBv4_be.lib	--code_state=16 --silicon_version=4 --endian=big
mylib_THUMBv4_le.lib	--code_state=16 --silicon_version=4 --endian=little
mylib_THUMBv7A8_le.lib	--code_state=16 --silicon_version=7A8 --endian=little

Using the library information archiver, you can create an index library called mylib.lib from the above libraries:

armlibinfo -o mylib.lib mylib_ARMv4_be.lib mylib_THUMBv4_be.lib
 mylib_THUMBv7A8_le.lib mylib_ARMv4_le.lib mylib_THUMBv4_le.lib

You can now specify mylib.lib as a library for the linker of an application. The linker uses the index library to choose the appropriate version of the library to use. If the --issue_remarks option is specified before the --run_linker option, the linker reports which library was chosen.

Example 1 (ISA v7A8, little endian):

   armcl-mv7A8 -me --mylib_pruv3_be main.c -z -l lnk.cmd ./mylib.lib
 <Linking> remark: linking in "mylib_THUMBv7A8_le.lib" in place of "mylib.lib"

Example 2 (ISAv5, big endian):

   armcl -mv5e --issue_remarks main.c -z -l lnk.cmd ./mylib.lib
 <Linking> remark: linking in "mylib_ARMv4_be.lib" in place of "mylib.lib"

In Example 2, there was no version of the library for ISAv5, but an ISAv4 library was available and is compatible, so it was used.

7.5.3 Listing the Contents of an Index Library

The archiver’s -t option can be used on an index library to list the archives indexed by an index library:

armar t mylib.lib

 SIZE DATE FILE NAME
 -------- ------------------------ -----------------
 119 Mon Apr 23 12:45:22 2007 mylib_ARMv4_be.lib.libinfo
 119 Mon Apr 23 12:45:22 2007 mylib_ARMv4_le.lib.libinfo
 119 Mon Apr 23 12:45:22 2007 mylib_THUMBv4_be.lib.libinfo
 119 Mon Apr 23 12:45:22 2007 mylib_THUMBv4_le.lib.libinfo
 119 Mon Apr 23 12:45:22 2007 mylib_THUMBv7A8_le.lib.libinfo
 0 Mon Apr 23 12:45:22 2007 __TI_$$LIBINFO

The indexed object file libraries have an additional .libinfo extension in the archiver listing. The __TI_$$LIBINFO member is a special member that designates mylib.lib as an index library, rather than a regular library.

If the archiver’s -d command is used on an index library to delete a .libinfo member, the linker will no longer choose the corresponding library when the index library is specified.

Using any other archiver option with an index library, or using -d to remove the __TI_$$LIBINFO member, results in undefined behavior, and is not supported.

7.5.4 Requirements

You must follow these requirements to use library index files:

At least one application object file must appear on the linker command line before the index library.
Each object file library specified as input to the library information archiver must only contain object file members that are built with the same build options.
The linker expects the index library and all of the libraries it indexes to be in a single directory.