LIBTOOL(1)LIBTOOL(1)NAMElibtool - create libraries
ranlib - add or update the table of contents of archive libraries
SYNOPSISlibtool-static-o output [ -sacLT ] [ - ] [ -arch_only arch_type ]
file... [-filelist listfile[,dirname]]
libtool-dynamic -o output [ -install_name name ] [ -compatibility_ver‐
sion number ] [ -current_version number ] [ link editor flags ] [ -v ]
[ -noall_load ] [ - ] [ -arch_only arch_type ] file... [-filelist
ranlib [ -sactfLT ] [ - ] archive...
The libtool command takes the specified input object files and creates
a library for use with the link editor, ld(1). The library's name is
specified by output (the argument to the -o flag). The input object
files may be in any correct format that contains object files (``fat''
files, archives, object files). Libtool will not put any non-object
input file into the output library (unlike ranlib, which allows this in
the archives it operates on).
When producing a ``fat'' file from objects of the same CPU type and
differing CPU subtypes, libtool and ranlib create at most one library
for each CPU type, rather than a separate library in a fat file for
each of the unique pairings of CPU type and CPU subtype. Thus, the
resulting CPU subtype for each library is the _ALL CPU subtype for that
CPU type. This strategy strongly encourages the implementor of a
library to create one library that chooses optimum code to run at run
time, rather than at link time.
Libtool can create either dynamically linked shared libraries, with
-dynamic, or statically linked (archive) libraries, with -static.
DYNAMICALLY LINKED SHARED LIBRARIES
Dynamically linked libraries, unlike statically linked libraries, are
Mach-O format files and not ar(5) format files. Dynamically linked
libraries have two restrictions: No symbol may be defined in more than
one object file and no common symbol can be used. To maximize sharing
of a dynamically linked shared library the objects should be compiled
with the -dynamic flag of cc(1) to produce indirect undefined refer‐
ences and position-independent code. To build a dynamically linked
library, libtool, runs the link editor, ld(1), with -dylib once for
each architecutre present in the input objects and then lipo(1) to cre‐
ate a fat file if needed.
ARCHIVE (or statically linked) LIBRARIES
Libtool with -static is intended to replace ar(5) and ranlib. For
backward compatibility, ranlib is still available, and it supports fat
files. Ranlib adds or updates the table of contents to each archive so
it can be linked by the link editor, ld(1). The table of contents is
an archive member at the beginning of the archive that indicates which
symbols are defined in which library members. Because ranlib rewrites
the archive, sufficient temporary file space must be available in the
file system that contains the current directory. Ranlib takes all cor‐
rect forms of libraries (fat files containing archives, and simple ar‐
chives) and updates the table of contents for all archives in the file.
Ranlib also takes one common incorrect form of archive, an archive
whose members are fat object files, adding or updating the table of
contents and producing the library in correct form (a fat file contain‐
ing multiple archives).
The archive member name for a table of contents begins with
``__.SYMDEF''. Currently, there are two types of table of contents
produced by libtool-static and ranlib and understood by the link edi‐
tor, ld(1). These are explained below, under the -s and -a options.
The following options pertain to libtool only.
Produce a statically linked (archive) library from the input
files. This is the default.
Produce a dynamically linked shared library from the input
ror a dynamic shared library this specifies the file name the
library will be installed in for programs that use it. If this
is not specified the name specified by the -o output option will
For a dynamic shared library this specifies the compatibility
version number of the library. When a library is used the com‐
patibility version is checked and if the user's version is
greater that the library's version, an error message is printed
and the using program exits. The format of number is X[.Y[.Z]]
where X must be a positive non-zero number less than or equal to
65535, and .Y and .Z are optional and if present must be non-
negative numbers less than or equal to 255. If this is not
specified then it has a value of 0 and no checking is done when
the library is used.
For dynamic shared library files this specifies the current ver‐
sion number of the library. The program using the library can
obtain the current version of the library programmatically to
determine exactly which version of the library it is using. The
format of number is X[.Y[.Z]] where X must be a positive non-
zero number less than or equal to 65535, and .Y and .Z are
optional and if present must be non-negative numbers less than
or equal to 255. If this is not specified then it has a value
For dynamic shared library files this specifies the the default
behavior of loading all members of archives on the command line
is not to be done. This option is used by the GNU compiler
driver, cc(1), when used with it's -dynamiclib option. This is
done to allow selective loading of the GNU's compiler's runtime
support library, libcc_dynamic.a .
link editor flags
For a dynamic shared library the following ld(1) flags are
accepted and passed through: -lx, -weak-lx, -search_paths_first
-weak_library, -Ldir, -ysym, -usym, -initsym, -idefinition:indi‐
rect, -seg1addr, -segs_read_only_addr, -segs_read_write_addr,
-seg_addr_table, -seg_addr_table_filename, -segprot, -segalign,
-sectcreate, -sectorder, -sectorder_detail, -sectalign, -unde‐
fined, -read_only_relocs, -prebind, -prebind_all_twolevel_mod‐
ules, -noprebind, -framework, -weak_framework, -umbrella,
-allowable_client, -sub_umbrella, -sub_library, -F, -U, -Y, -Sn,
-Si, -S, -X, -x, -whyload, -all_load.-arch_errors_fatal,
-dylib_file, -run_init_lazily, -final_output, -multiply_defined,
-multiply_defined_unused, -twolevel_namespace, -twolevel_names‐
pace_hints, -flat_namespace, -nomultidefs, -headerpad, -header‐
pad_max_install_names, -weak_reference_mismatches, -M,
-no_arch_warnings, -single_module, -multi_module, -exported_sym‐
bols_list, -unexported_symbols_list, -m. See the ld(1) man page
for details on these flags. The flag -image_base is a synonym
-v Verbose mode, which prints the ld(1) commands and lipo(1) com‐
The listfile contains a list of file names and is an alternative
way of specifiying file names on the command line. The file
names are listed one per line separated only by newlines (spaces
and tabs are assumed to be part of the file name). If the
optional directory name, dirname is specified then it is
prepended to each name in the list file.
This option causes libtool to build a library only for the spec‐
ified arch_type and ignores all other architectures in the input
files. When building a dynamic library, if this is specified
with a specific cpusubtype other than the family cpusubtype then
libtool it does not use the ld(1)-force_cpusubtype_ALL flag and
passes the -arch_only argument to ld(1) as the -arch flag so
that the output is tagged with that cpusubtype.
The following options pertain to the table of contents for an archive
library, and apply to both libtool-static and ranlib:
-s Produce the preferred type of table of contents, which results
in faster link editing when linking with the archive. The order
of the table of contents is sorted by symbol name. The library
member name of this type of table of contents is ``__.SYMDEF
SORTED''. This type of table of contents can only be produced
when the library does not have multiple members that define the
same symbol. This is the default.
-a Produce the original type of table of contents, whose order is
based on the order of the members in the archive. The library
member name of this type of table of contents is ``__.SYMDEF''.
This type of table of contents must be used when the library has
multiple members that define the same symbol.
-c Include common symbols as definitions with respect to the table
of contents. This is seldom the intended behavior for linking
from a library, as it forces the linking of a library member
just because it uses an uninitialized global that is undefined
at that point in the linking. This option is included only
because this was the original behavior of ranlib. This option
is not the default.
-L Use the 4.4bsd archive extended format #1, which allows archive
member names to be longer than 16 characters and have spaces in
their names. This option is the default.
-T Truncate archive member names to 16 characters and don't use the
4.4bsd extended format #1. This option is not the default.
-f Warns when the output archive is fat and ar(1) will no longer be
able to operate on it.
For compatibility, the following ranlib option is accepted (but
-t This option used to request that ranlib only ``touch'' the ar‐
chives instead of modifying them. The option is now ignored,
and the table of contents is rebuilt.
One other option applies to both libtool and ranlib:
- Treat all remaining arguments as names of files (or archives)
and not as options.
SEE ALSOld(1), ar(1), otool(1), make(1), redo_prebinding(1), ar(5)BUGS
With the way libraries used to be created, errors were possible if the
library was modified with ar(1) and the table of contents was not
updated by rerunning ranlib(1). Thus the link editor, ld, warns when
the modification date of a library is more recent than the creation
date of its table of contents. Unfortunately, this means that you get
the warning even if you only copy the library.
Apple Computer, Inc. July 11, 2003 LIBTOOL(1)