Unix/Linux Go Back    


OSX 10.6.2 - man page for libtool (osx section 1)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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

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

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

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

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  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)
Unix & Linux Commands & Man Pages : ©2000 - 2017 Unix and Linux Forums


All times are GMT -4. The time now is 11:43 PM.