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 [ -sacLT ] [ - ] [ -arch_only arch_type ] 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 imple-
       mentor 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 shar-
       ing 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  uni-
       versal  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.

       -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  compati-
	      bility 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_ref-
	      erence_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.

       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.

       One other option applies to both libtool and ranlib:

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

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.							September 24, 2008							LIBTOOL(1)