The granlib Utility Program creates a table of contents (TOC) at the beginning of an archive.
Exactly one archive (created by ax) may be given to granlib.
The -dump option does not modify the archive. Instead, it prints the existing TOC, listing each symbol name, followed by the byte offset within the archive for the object file containing that symbol. It also prints the name of every object file, followed by its offset. This option is primarily intended for debugging.
There are three tools which work together with archives:
granlib Modifies an archive, adding a TOC.
Creating a TOC has two benefits when linking archives with lx.
Normally when the linker reads an archive, it first reads through the entire archive, looking for global-defined symbols. A list of all symbols, as well as which files they appear in, is created. Then the linker goes through the list of defined symbols, checking if any of the symbols are referenced by the preceding object files. If a symbol is referenced, the corresponding object file will be extract from the archive and will be added to the output file. The list of symbols is checked repeatedly until no further symbols can be resolved. At this point the linker closes the archive and never uses it again to resolve symbol references.
The first benefit is to create the TOC in advance, rather than having lx create it every time the archive is read. This significantly improves performance. Since an archive is normally built once and read many times, it is worthwhile to run the granlib Utility Program on an archive to gain this improvement.
The second benefit is that lx is able to rescan libraries that have a TOC. As described above, normally lx will only process an archive once. Any symbols which are referenced after an archive has been processed will not be resolved by that archive. The -rescan option directs lx to repeat processing of archives indefinitely if there are unresolved symbols at the end of the link. In this way, references between archives are never left unresolved due to ordering problems between archives. This does decrease performance, but the impact is reduced because the TOC for each archive is retained in memory.
The granlib Utility Program should be run on an archive every time it is modified by ax. ax always discards any existing TOC when the archive is modified. This ensures that an outdated TOC is never left within the archive.
The current version of build (1.8.8) does not invoke the granlib Utility Program automatically. In the next release, build will invoke granlib automatically so that all archives which are built directly from within MULTI or with the -archive option to the compiler driver will have their TOC updated.
The Green Hills libraries do not currently have the TOC created by granlib. This may be safely done by the user.
granlib is only supported with ELF archives.