Unix/Linux Go Back    


OpenDarwin 7.2.1 - man page for libtool (opendarwin 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 ] file...  [-filelist listfile[,dirname]]

       ranlib [ -sactfLT ] [ - ] 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  (``fat'' 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  ``fat''  file from objects of the same CPU type and differing CPU sub-
       types, libtool and ranlib create at most one library for each CPU type, rather than a sep-
       arate  library  in a fat 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 architecutre present in the input objects and then lipo(1) to create
       a fat 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 fat 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 con-
       tents  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 direc-
       tory.  Ranlib takes all correct forms of libraries (fat	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  fat  object
       files,  adding or updating the table of contents and producing the library in correct form
       (a fat 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
	      ror  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, -noprebind, -framework,
	      -weak_framework, -umbrella, -allowable_client, -sub_umbrella, -sub_library, -F, -U,
	      -Y,  -Sn,  -Si,  -S, -X, -x, -whyload, -all_load.  -arch_errors_fatal, -dylib_file,
	      -run_init_lazily,   -final_output,   -multiply_defined,	-multiply_defined_unused,
	      -twolevel_namespace,   -twolevel_namespace_hints,   -flat_namespace,  -nomultidefs,
	      -headerpad,    -headerpad_max_install_names,    -weak_reference_mismatches,     -M,
	      -no_arch_warnings,  -single_module,  -multi_module,  -exported_symbols_list, -unex-
	      ported_symbols_list, -m.	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.

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

       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).  Thus
       the link editor, ld, warns when the modification date of a library is more recent than the
       creation  date of its table of contents.  Unfortunately, this means that you get the warn-
       ing even if you only copy the library.

Apple Computer, Inc.			  July 11, 2003 			       LIBTOOL(1)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 06:08 PM.