manpagez: man pages & more
man libtool(1)
Home | html | info | man
libtool(1)                                                          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 ] [
       -no_warning_for_no_symbols ] 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  ]  [  -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  (``uni-
       versal'' 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 univer-
       sal 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 sub-
       type 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  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 architecture present in the input objects and then lipo(1) to cre-
       ate 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 ar-
       chive so it can be linked by the link editor, ld(1).  The table of con-
       tents is an archive member at the beginning of the archive  that  indi-
       cates which symbols are defined in which library members.  Because ran-
       lib rewrites the archive,  sufficient  temporary  file  space  must  be
       available in the file system that contains the current directory.  Ran-
       lib 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 edi-
       tor, 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  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.

       -current_version number
              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
              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: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,    -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,  -multi-
              ply_defined_unused,     -twolevel_namespace,    -twolevel_names-
              pace_hints, -flat_namespace, -nomultidefs, -headerpad,  -header-
              pad_max_install_names,   -weak_reference_mismatches,   -M,   -t,
              -no_arch_warnings, -single_module, -multi_module, -exported_sym-
              bols_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)  com-
              mands 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 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 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  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.

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


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  modi-
       fied and the table of contents is not updated.



Apple Inc.                     January 27, 2014                     libtool(1)

Mac OS X 10.11.6 - Generated Thu Feb 2 18:07:48 CST 2017
© manpagez.com 2000-2017
Individual documents may contain additional copyright information.