libtool - create libraries
ranlib - add or update the table of contents of archive libraries
libtool -static -o output [ -sacLT ] [ - ] [ -arch_only arch_type ] file... [-filelist
libtool -dynamic -o output [ -install_name name ] [ -compatibility_version number ] [
-current_version number ] [ link editor flags ] [ -v ] [ -noall_load ] [ - ] [ -arch_only
arch_type ] [ -V ] file... [-filelist listfile[,dirname]]
ranlib [ -sactfqLT ] [ - ] 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 (``universal'' 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
When producing a ``universal'' 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 universal 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 stati-
cally 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 references and position-independent
code. To build a dynamically linked library, libtool, runs the link editor, ld(1), with
-dylib once for each architecture present in the input objects and then lipo(1) to create
a universal 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 universal files. Ranlib adds or updates the
table of contents to each archive so it can be linked by the link editor, ld(1). The ta-
ble 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, suffi-
cient temporary file space must be available in the file system that contains the current
directory. Ranlib takes all correct forms of libraries (universal files containing ar-
chives, and simple archives) 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 universal object files, adding or updating the table of contents and producing the
library in correct form (a universal file containing 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 under-
stood by the link editor, 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
Produce a dynamically linked shared library from the input files.
For 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 be used.
For a dynamic shared library, this specifies the compatibility version number of
the library. When a library is used the compatibility 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 version 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 num-
ber 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.
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,
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:indirect, -seg1addr, -segs_read_only_addr,
-segs_read_write_addr, -seg_addr_table, -seg_addr_table_filename, -segprot,
-segalign, -sectcreate, -sectorder, -sectorder_detail, -sectalign, -undefined,
-read_only_relocs, -prebind, -prebind_all_twolevel_modules, -prebind_allow_overlap,
-noprebind, -framework, -weak_framework, -umbrella, -allowable_client,
-sub_umbrella, -sub_library, -F, -U, -Y, -Sn, -Si, -Sp, -S, -X, -x, -whyload,
-all_load. -arch_errors_fatal, -dylib_file, -run_init_lazily, -final_output,
-macosx_version_min, -multiply_defined, -multiply_defined_unused, -twolevel_names-
pace, -twolevel_namespace_hints, -flat_namespace, -nomultidefs, -headerpad, -head-
erpad_max_install_names, -weak_reference_mismatches, -M, -t, -no_arch_warnings,
-single_module, -multi_module, -exported_symbols_list, -unexported_symbols_list,
-m, -dead_strip, -no_dead_strip_inits_and_terms, -executable_path, -syslibroot,
-no_uuid. See the ld(1) man page for details on these flags. The flag -image_base
is a synonym for -seg1addr.
-v Verbose mode, which prints the ld(1) commands and lipo(1) commands executed.
-V Print the version of libtool.
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 specified 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 edit-
ing 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
-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 link-
ing of a library member just because it uses an uninitialized global that is unde-
fined 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
-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 universal and ar(1) will no longer be able to
operate on it.
-q Do nothing if a universal file would be created.
For compatibility, the following ranlib option is accepted (but ignored):
-t This option used to request that ranlib only ``touch'' the archives instead of mod-
ifying 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.
ld(1), ar(1), otool(1), make(1), redo_prebinding(1), ar(5)
With the way libraries used to be created, errors were possible if the library was modi-
fied with ar(1) and the table of contents was not updated by rerunning ranlib(1). So pre-
viously the link editor, ld(1), generated an error when the modification date of a library
was more recent than the creation date of its table of contents. Unfortunately, this
meant that you got the error even if you only copy the library. Since this error was
found to be too much of a nuisance it was removed. So now it is possible again to get
link errors if the library is modified and the table of contents is not updated.
Apple Inc. September 24, 2008 LIBTOOL(1)