ARM Technical Support Knowledge Articles

Why does armlink treat libraries differently to objects?

Applies to: ARM Developer Suite (ADS), RealView Developer Kit (RVDK) for OKI, RealView Developer Kit (RVDK) for ST, RealView Developer Kit for XScale (RVXDK), RealView Development Suite (RVDS)


A library is simply a collection of objects and can be added to a link line in the same way an object can be. However the linker treats objects within a library differently to objects specified on the command line.

The following is a functional description of what happens during the linking process (obviously there are various opportunities for optimisation);

  • When armlink is invoked it reads the list of objects, libraries and symbol files given as input.
  • It loads all the objects and symbol files but does not load the libraries.
  • It builds a list of all the symbols defined by the objects and symbol files - the symbol definitions.
  • It builds a list of symbols that the objects try to use (e.g. function calls). These are the symbol references.
  • The linker eliminates from this list all the symbol references that have a matching definition (these references have been resolved).

Depending on the application you are building there might be no symbol references left in the list in which case the link is finished and no libraries are required.

Typically however there are some references left in the list and at this stage (and only at this stage) the linker begins searching the libraries to find suitable matching definitions.

  • The linker reads the symbol table of the libraries in the order given on the command line, followed by the standard ARM libraries.
  • If the symbol table of the library contains a symbol which we are looking for (i.e. one on the symbol references list) then the linker will load the object that defines that symbol (it does not load all the objects in the library) and updates the list of symbol definitions and references. It then restarts scanning the libraries to resolve the next reference.

Once all the references have been resolved the linking process has finished and the linker stops reading library symbol tables and loading library objects.

If all the libraries have been scanned and there are still symbol references left then these are considered to be unresolved and an error is raised.

This process is documented in the Creating and Using libraries section of the Linker and Utilities guide supplied with the tools and can be better understood by looking at the output of the --verbose switch (-verbose in ADS) i.e.

armlink --verbose -o image.axf a.o b.o c.o lib.a

The --verbose switch is extremely useful in diagnosing link problems.

This process has various intended consequences; the most common are listed below.

  • --keep, --first & --last do not force an object in a library to be linked into the final image. If an object in a library is never required then it will not be loaded by the linker. --keep, --first and --last only work with objects actually loaded by the linker.
  • In a similar way --noremove will not force objects to be included from libraries. It will only stop objects already included to satisfy a reference from being eliminated.
  • Using --entry to place the ELF entry point in a library object can have odd effects especially if the object is not loaded.
  • Multiple definitions of a symbol in different library objects are not necessarily detected. Once the linker has found a suitable definition for a symbol it stops looking for others. Assuming the object containing the duplicate symbol is not loaded for other reasons no error will occur. This is intentional and particularly useful in some situations.
  • At least one object must be listed for the link step to do anything.
  • Loading one object from a library does not imply that all the other objects in the library will be loaded.
  • A $Sub$$function type symbol defined in a library object will only override the original function if the object is loaded to define another symbol. In other words the linker does not search library objects for $Sub$$function symbols, it only acts on them once they have been loaded.
  • If your own definition of a library symbol appears before the library is scanned then you can replace the library definition. You may have to define other symbols too otherwise the library object will be required to resolve these and a multiple symbol definition error will occur.

If you have a library and wish to force an object within it to be loaded by the linker then you should refer to that object and library explicitly on the linker command line like this;

armlink -o image.axf a.o b.o c.o lib.a(important_object.o)

A library is typically useful where there are optional pieces of code in your system (perhaps dependent on hardware configuration and you wish to allow the linker to make the selection). They are also useful for providing code to customers who will be changing such a configuration. They are not especially useful for packaging up a large number of objects all of which will be required in the final link step. In this case objects should be partially linked instead to create a single, large, combined object. Partial linking is accomplished with

armlink --partial -o combined_object.o a.o b.o c.o

System libraries will not be included in the combined object. Partial linking has several advantages including reducing debug information and a faster final link step.

Article last edited on: 2009-04-16 16:00:52

Rate this article

Disagree? Move your mouse over the bar and click

Did you find this article helpful? Yes No

How can we improve this article?

Link to this article
Copyright © 2011 ARM Limited. All rights reserved. External (Open), Non-Confidential