10.6.3. Resolving Symbols with Object Libraries

An object library is a partitioned archive file that contains object files as members. Usually, a group of related modules are grouped together into a library. When you specify an object library as linker input, the linker includes any members of the library that define existing unresolved symbol references. You can use the archiver to build and maintain libraries. Archiver Description contains more information about the archiver.

Using object libraries can reduce link time and the size of the executable module. Normally, if an object file that contains a function is specified at link time, the file is linked whether the function is used or not; however, if that same function is placed in an archive library, the file is included only if the function is referenced.

The order in which libraries are specified is important, because the linker includes only those members that resolve symbols that are undefined at the time the library is searched. The same library can be specified as often as necessary; it is searched each time it is included. Alternatively, you can use the --reread_libs option to reread libraries until no more references can be resolved (see Exhaustively Read and Search Libraries (--reread_libs and --priority Options). A library has a table that lists all external symbols defined in the library; the linker searches through the table until it determines that it cannot use the library to resolve any more references.

The following examples link several files and libraries, using these assumptions:

  • Input files f1.c.o and f2.c.o both reference an external function named clrscr.

  • Input file f1.c.o references the symbol origin.

  • Input file f2.c.o references the symbol fillclr.

  • Member 0 of library libc.lib contains a definition of origin.

  • Member 3 of library liba.lib contains a definition of fillclr.

  • Member 1 of both libraries defines clrscr.

If you enter:

tiarmclang f1.c.o f2.c.o liba.lib libc.lib

then:

  • Member 1 of liba.lib satisfies the f1.c.o and f2.c.o references to clrscr because the library is searched and the definition of clrscr is found.

  • Member 0 of libc.lib satisfies the reference to origin.

  • Member 3 of liba.lib satisfies the reference to fillclr.

If, however, you enter:

tiarmclang f1.c.o f2.c.o libc.lib liba.lib

then the references to clrscr are satisfied by member 1 of libc.lib.

If none of the linked files reference symbols defined in a library, you can use the --undef_sym option to force the linker to include a library member. (See Introduce an Unresolved Symbol (--undef_sym Option).) The next example creates an undefined symbol rout1 in the linker’s global symbol table:

tiarmclang -Wl,--undef_sym=rout1 libc.lib

If any member of libc.lib defines rout1, the linker includes that member.

Library members are allocated according to the SECTIONS directive default allocation algorithm; see The SECTIONS Directive.

Alter the Library Search Algorithm (--library, --search_path) describes methods for specifying directories that contain object libraries.