LIBTOOL(1)                  General Commands Manual                 LIBTOOL(1)

NAME
       libtool - create libraries
       ranlib - add or update the table of contents of archive libraries

SYNOPSIS
       libtool -static -o output [ -sacLTD ] [ - ] [ -arch_only arch_type ] [
       -no_warning_for_no_symbols ] file...  [-filelist listfile[,dirname]]

       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...

DESCRIPTION
       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 operates on).

       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 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
       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 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 correct forms of libraries (universal files containing
       archives, 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 understood by the link
       editor, ld(1).  These are explained below, under the -s and -a options.

OPTIONS
       The following options pertain to libtool only.

       @file  Arguments beginning with @ are replaced by arguments read from
              the specified file, as an alternative to listing those arguments
              on the command line. The files simply contain libtool options
              and files separated by whitespace: spaces, tabs, and newlines.
              Characters can be escaped with a backslash (\), including
              whitespace characters and other backslashes. Also, arguments
              that include whitespace can be enclosed, wholly or in part, by
              single- or double-quote charcters. These files may contain @file
              references to additional files, although libtool will error on
              include cycles.  If a file cannot be found, the original @file
              argument will remain in the argument list.

       -static
              Produce a statically linked (archive) library from the input
              files.  This is the default.

       -dynamic
              Produce a dynamically linked shared library from the input
              files.

       -install_name name
              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.

       -compatibility_version number
              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.

       -current_version number
              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 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.

       -noall_load
              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: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_namespace,
              -twolevel_namespace_hints, -flat_namespace, -nomultidefs,
              -headerpad, -headerpad_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.

       -filelist listfile[,dirname]
              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.

       -arch_only arch_type
              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 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 universal and ar(1) will no
              longer be able to operate on it.

       -q     Do nothing if a universal file would be created.

       -D     When building a static library, set archive contents' user ids,
              group ids, dates, and file modes to reasonable defaults. This
              allows libraries created with identical input to be identical to
              each other, regardless of time of day, user, group, umask, and
              other aspects of the environment.

       For compatibility, the following ranlib option is accepted (but
       ignored):

       -t     This option used to request that ranlib only ``touch'' the
              archives instead of modifying them.  The option is now ignored,
              and the table of contents is rebuilt.

       Other options applying to both libtool and ranlib:

       -      Treat all remaining arguments as names of files (or archives)
              and not as options.

       -no_warning_for_no_symbols
              Don't warn about file that have no symbols.

       -dependency_info path
              Write an Xcode dependency info file describing a successful
              build operation.  This file describes the inputs directly or
              indirectly used to create the library or dylib.

SEE ALSO
       ld(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).  So previously 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.                       June 23, 2020                      LIBTOOL(1)