cript contents,  Next: Cheap tricks,  Prev: Platform quirks,  Up: Maintaining

15.4 'libtool' script contents
==============================

Since version 1.4, the 'libtool' script is generated by 'configure'
(*note Configuring::).  In earlier versions, 'configure' achieved this
by calling a helper script called 'ltconfig'.  From libtool version 0.7
to 1.0, this script simply set shell variables, then sourced the libtool
backend, 'ltmain.sh'.  'ltconfig' from libtool version 1.1 through 1.3
inlined the contents of 'ltmain.sh' into the generated 'libtool', which
improved performance on many systems.  The tests that 'ltconfig' used to
perform are now kept in 'libtool.m4' where they can be written using
Autoconf.  This has the runtime performance benefits of inlined
'ltmain.sh', _and_ improves the build time a little while considerably
easing the amount of raw shell code that used to need maintaining.

   The convention used for naming variables that hold shell commands for
delayed evaluation, is to use the suffix '_cmd' where a single line of
valid shell script is needed, and the suffix '_cmds' where multiple
lines of shell script *may* be delayed for later evaluation.  By
convention, '_cmds' variables delimit the evaluation units with the '~'
character where necessary.

   Here is a listing of each of the configuration variables, and how
they are used within 'ltmain.sh' (*note Configuring::):

 -- Variable: AR
     The name of the system library archiver.

 -- Variable: CC
     The name of the compiler used to configure libtool.  This will
     always contain the compiler for the current language (*note
     Tags::).

 -- Variable: ECHO
     An 'echo' program that does not interpret backslashes as an escape
     character.  It may be given only one argument, so due quoting is
     necessary.

 -- Variable: LD
     The name of the linker that libtool should use internally for
     reloadable linking and possibly shared libraries.

 -- Variable: LTCC
 -- Variable: LTCFLAGS
     The name of the C compiler and C compiler flags used to configure
     libtool.

 -- Variable: NM
     The name of a BSD- or MS-compatible program that produces listings
     of global symbols.  For BSD 'nm', the symbols should be in one the
     following formats:

          ADDRESS C GLOBAL-VARIABLE-NAME
          ADDRESS D GLOBAL-VARIABLE-NAME
          ADDRESS T GLOBAL-FUNCTION-NAME

     For MS 'dumpbin', the symbols should be in one of the following
     formats:

          COUNTER SIZE    UNDEF    notype       External     | GLOBAL-VAR
          COUNTER ADDRESS SECTION  notype       External     | GLOBAL-VAR
          COUNTER ADDRESS SECTION  notype ()    External     | GLOBAL-FUNC

     The SIZE of the global variables are not zero and the SECTION of
     the global functions are not "UNDEF". Symbols in "pick any"
     sections ("pick any" appears in the section header) are not global
     either.

 -- Variable: RANLIB
     Set to the name of the 'ranlib' program, if any.

 -- Variable: allow_undefined_flag
     The flag that is used by 'archive_cmds' to declare that there will
     be unresolved symbols in the resulting shared library.  Empty, if
     no such flag is required.  Set to 'unsupported' if there is no way
     to generate a shared library with references to symbols that aren't
     defined in that library.

 -- Variable: always_export_symbols
     Whether libtool should automatically generate a list of exported
     symbols using 'export_symbols_cmds' before linking an archive.  Set
     to 'yes' or 'no'.  Default is 'no'.

 -- Variable: archive_cmds
 -- Variable: archive_expsym_cmds
 -- Variable: old_archive_cmds
     Commands used to create shared libraries, shared libraries with
     '-export-symbols' and static libraries, respectively.

 -- Variable: archiver_list_spec
     Specify filename containing input files for 'AR'.

 -- Variable: old_archive_from_new_cmds
     If the shared library depends on a static library,
     'old_archive_from_new_cmds' contains the commands used to create
     that static library.  If this variable is not empty,
     'old_archive_cmds' is not used.

 -- Variable: old_archive_from_expsyms_cmds
     If a static library must be created from the export symbol list to
     correctly link with a shared library,
     'old_archive_from_expsyms_cmds' contains the commands needed to
     create that static library.  When these commands are executed, the
     variable 'soname' contains the name of the shared library in
     question, and the '$objdir/$newlib' contains the path of the static
     library these commands should build.  After executing these
     commands, libtool will proceed to link against '$objdir/$newlib'
     instead of 'soname'.

 -- Variable: lock_old_archive_extraction
     Set to 'yes' if the extraction of a static library requires locking
     the library file.  This is required on Darwin.

 -- Variable: build
 -- Variable: build_alias
 -- Variable: build_os
     Set to the specified and canonical names of the system that libtool
     was built on.

 -- Variable: build_libtool_libs
     Whether libtool should build shared libraries on this system.  Set
     to 'yes' or 'no'.

 -- Variable: build_old_libs
     Whether libtool should build static libraries on this system.  Set
     to 'yes' or 'no'.

 -- Variable: compiler_c_o
     Whether the compiler supports the '-c' and '-o' options
     simultaneously.  Set to 'yes' or 'no'.

 -- Variable: compiler_needs_object
     Whether the compiler has to see an object listed on the command
     line in order to successfully invoke the linker.  If 'no', then a
     set of convenience archives or a set of object file names can be
     passed via linker-specific options or linker scripts.

 -- Variable: dlopen_support
     Whether 'dlopen' is supported on the platform.  Set to 'yes' or
     'no'.

 -- Variable: dlopen_self
     Whether it is possible to 'dlopen' the executable itself.  Set to
     'yes' or 'no'.

 -- Variable: dlopen_self_static
     Whether it is possible to 'dlopen' the executable itself, when it
     is linked statically ('-all-static').  Set to 'yes' or 'no'.

 -- Variable: exclude_expsyms
     List of symbols that should not be listed in the preloaded symbols.

 -- Variable: export_dynamic_flag_spec
     Compiler link flag that allows a dlopened shared library to
     reference symbols that are defined in the program.

 -- Variable: export_symbols_cmds
     Commands to extract exported symbols from 'libobjs' to the file
     'export_symbols'.

 -- Variable: extract_expsyms_cmds
     Commands to extract the exported symbols list from a shared
     library.  These commands are executed if there is no file
     '$objdir/$soname-def', and should write the names of the exported
     symbols to that file, for the use of
     'old_archive_from_expsyms_cmds'.

 -- Variable: fast_install
     Determines whether libtool will privilege the installer or the
     developer.  The assumption is that installers will seldom run
     programs in the build tree, and the developer will seldom install.
     This is only meaningful on platforms where
     'shlibpath_overrides_runpath' is not 'yes', so 'fast_install' will
     be set to 'needless' in this case.  If 'fast_install' set to 'yes',
     libtool will create programs that search for installed libraries,
     and, if a program is run in the build tree, a new copy will be
     linked on-demand to use the yet-to-be-installed libraries.  If set
     to 'no', libtool will create programs that use the
     yet-to-be-installed libraries, and will link a new copy of the
     program at install time.  The default value is 'yes' or 'needless',
     depending on platform and configuration flags, and it can be turned
     from 'yes' to 'no' with the configure flag
     '--disable-fast-install'.

     On some systems, the linker always hardcodes paths to dependent
     libraries into the output.  In this case, 'fast_install' is never
     set to 'yes', and relinking at install time is triggered.  This
     also means that 'DESTDIR' installation does not work as expected.

 -- Variable: file_magic_glob
     How to find potential files when 'deplibs_check_method' is
     'file_magic'.  'file_magic_glob' is a 'sed' expression, and the
     'sed' instance is fed potential file names that are transformed by
     the 'file_magic_glob' expression.  Useful when the shell does not
     support the shell option 'nocaseglob', making 'want_nocaseglob'
     inappropriate.  Normally disabled (i.e.  'file_magic_glob' is
     empty).

 -- Variable: finish_cmds
     Commands to tell the dynamic linker how to find shared libraries in
     a specific directory.

 -- Variable: finish_eval
     Same as 'finish_cmds', except the commands are not displayed.

 -- Variable: global_symbol_pipe
     A pipeline that takes the output of 'NM', and produces a listing of
     raw symbols followed by their C names.  For example:

          $ eval "$NM progname | $global_symbol_pipe"
          D SYMBOL1 C-SYMBOL1
          T SYMBOL2 C-SYMBOL2
          C SYMBOL3 C-SYMBOL3
          ...
          $

     The first column contains the symbol type (used to tell data from
     code) but its meaning is system dependent.

 -- Variable: global_symbol_to_cdecl
     A pipeline that translates the output of 'global_symbol_pipe' into
     proper C declarations.  Since some platforms, such as HP/UX, have
     linkers that differentiate code from data, data symbols are
     declared as data, and code symbols are declared as functions.

 -- Variable: hardcode_action
     Either 'immediate' or 'relink', depending on whether shared library
     paths can be hardcoded into executables before they are installed,
     or if they need to be relinked.

 -- Variable: hardcode_direct
     Set to 'yes' or 'no', depending on whether the linker hardcodes
     directories if a library is directly specified on the command line
     (such as 'DIR/libNAME.a') when 'hardcode_libdir_flag_spec' is
     specified.

 -- Variable: hardcode_direct_absolute
     Some architectures hardcode "absolute" library directories that
     cannot be overridden by 'shlibpath_var' when 'hardcode_direct' is
     'yes'.  In that case set 'hardcode_direct_absolute' to 'yes', or
     otherwise 'no'.

 -- Variable: hardcode_into_libs
     Whether the platform supports hardcoding of run-paths into
     libraries.  If enabled, linking of programs will be much simpler
     but libraries will need to be relinked during installation.  Set to
     'yes' or 'no'.

 -- Variable: hardcode_libdir_flag_spec
     Flag to hardcode a 'libdir' variable into a binary, so that the
     dynamic linker searches 'libdir' for shared libraries at runtime.
     If it is empty, libtool will try to use some other hardcoding
     mechanism.

 -- Variable: hardcode_libdir_separator
     If the compiler only accepts a single 'hardcode_libdir_flag', then
     this variable contains the string that should separate multiple
     arguments to that flag.

 -- Variable: hardcode_minus_L
     Set to 'yes' or 'no', depending on whether the linker hardcodes
     directories specified by '-L' flags into the resulting executable
     when 'hardcode_libdir_flag_spec' is specified.

 -- Variable: hardcode_shlibpath_var
     Set to 'yes' or 'no', depending on whether the linker hardcodes
     directories by writing the contents of '$shlibpath_var' into the
     resulting executable when 'hardcode_libdir_flag_spec' is specified.
     Set to 'unsupported' if directories specified by '$shlibpath_var'
     are searched at run time, but not at link time.

 -- Variable: host
 -- Variable: host_alias
 -- Variable: host_os
     Set to the specified and canonical names of the system that libtool
     was configured for.

 -- Variable: include_expsyms
     List of symbols that must always be exported when using
     'export_symbols'.

 -- Variable: inherit_rpath
     Whether the linker adds runtime paths of dependency libraries to
     the runtime path list, requiring libtool to relink the output when
     installing.  Set to 'yes' or 'no'.  Default is 'no'.

 -- Variable: install_override_mode
     Permission mode override for installation of shared libraries.  If
     the runtime linker fails to load libraries with wrong permissions,
     then it may fail to execute programs that are needed during
     installation, because these need the library that has just been
     installed.  In this case, it is necessary to pass the mode to
     'install' with '-m INSTALL_OVERRIDE_MODE'.

 -- Variable: libext
     The standard old archive suffix (normally 'a').

 -- Variable: libname_spec
     The format of a library name prefix.  On all Unix systems, static
     libraries are called 'libNAME.a', but on some systems (such as OS/2
     or MS-DOS), the library is just called 'NAME.a'.

 -- Variable: library_names_spec
     A list of shared library names.  The first is the name of the file,
     the rest are symbolic links to the file.  The name in the list is
     the file name that the linker finds when given '-lNAME'.

 -- Variable: link_all_deplibs
     Whether libtool must link a program against all its dependency
     libraries.  Set to 'yes' or 'no'.  Default is 'unknown', which is a
     synonym for 'yes'.

 -- Variable: link_static_flag
     Linker flag (passed through the C compiler) used to prevent dynamic
     linking.

 -- Variable: macro_version
 -- Variable: macro_revision
     The release and revision from which the libtool.m4 macros were
     taken.  This is used to ensure that macros and 'ltmain.sh'
     correspond to the same Libtool version.

 -- Variable: max_cmd_len
     The approximate longest command line that can be passed to '$SHELL'
     without being truncated, as computed by 'LT_CMD_MAX_LEN'.

 -- Variable: need_lib_prefix
     Whether we can 'dlopen' modules without a 'lib' prefix.  Set to
     'yes' or 'no'.  By default, it is 'unknown', which means the same
     as 'yes', but documents that we are not really sure about it.  'no'
     means that it is possible to 'dlopen' a module without the 'lib'
     prefix.

 -- Variable: need_version
     Whether versioning is required for libraries, i.e. whether the
     dynamic linker requires a version suffix for all libraries.  Set to
     'yes' or 'no'.  By default, it is 'unknown', which means the same
     as 'yes', but documents that we are not really sure about it.

 -- Variable: need_locks
     Whether files must be locked to prevent conflicts when compiling
     simultaneously.  Set to 'yes' or 'no'.

 -- Variable: nm_file_list_spec
     Specify filename containing input files for 'NM'.

 -- Variable: no_builtin_flag
     Compiler flag to disable builtin functions that conflict with
     declaring external global symbols as 'char'.

 -- Variable: no_undefined_flag
     The flag that is used by 'archive_cmds' to declare that there will
     be no unresolved symbols in the resulting shared library.  Empty,
     if no such flag is required.

 -- Variable: objdir
     The name of the directory that contains temporary libtool files.

 -- Variable: objext
     The standard object file suffix (normally 'o').

 -- Variable: pic_flag
     Any additional compiler flags for building library object files.

 -- Variable: postinstall_cmds
 -- Variable: old_postinstall_cmds
     Commands run after installing a shared or static library,
     respectively.

 -- Variable: postuninstall_cmds
 -- Variable: old_postuninstall_cmds
     Commands run after uninstalling a shared or static library,
     respectively.

 -- Variable: postlink_cmds
     Commands necessary for finishing linking programs.  'postlink_cmds'
     are executed immediately after the program is linked.  Any
     occurrence of the string '@OUTPUT@' in 'postlink_cmds' is replaced
     by the name of the created executable (i.e. not the wrapper, if a
     wrapper is generated) prior to execution.  Similarly,
     '@TOOL_OUTPUT@' is replaced by the toolchain format of '@OUTPUT@'.
     Normally disabled (i.e. 'postlink_cmds' empty).

 -- Variable: reload_cmds
 -- Variable: reload_flag
     Commands to create a reloadable object.  Set 'reload_cmds' to
     'false' on systems that cannot create reloadable objects.

 -- Variable: runpath_var
     The environment variable that tells the linker what directories to
     hardcode in the resulting executable.

 -- Variable: shlibpath_overrides_runpath
     Indicates whether it is possible to override the hard-coded library
     search path of a program with an environment variable.  If this is
     set to no, libtool may have to create two copies of a program in
     the build tree, one to be installed and one to be run in the build
     tree only.  When each of these copies is created depends on the
     value of 'fast_install'.  The default value is 'unknown', which is
     equivalent to 'no'.

 -- Variable: shlibpath_var
     The environment variable that tells the dynamic linker where to
     find shared libraries.

 -- Variable: soname_spec
     The name coded into shared libraries, if different from the real
     name of the file.

 -- Variable: striplib
 -- Variable: old_striplib
     Command to strip a shared ('striplib') or static ('old_striplib')
     library, respectively.  If these variables are empty, the strip
     flag in the install mode will be ignored for libraries (*note
     Install mode::).

 -- Variable: sys_lib_dlsearch_path_spec
     Expression to get the run-time system library search path.
     Directories that appear in this list are never hard-coded into
     executables.

 -- Variable: sys_lib_search_path_spec
     Expression to get the compile-time system library search path.
     This variable is used by libtool when it has to test whether a
     certain library is shared or static.  The directories listed in
     'shlibpath_var' are automatically appended to this list, every time
     libtool runs (i.e., not at configuration time), because some
     linkers use this variable to extend the library search path.
     Linker switches such as '-L' also augment the search path.

 -- Variable: thread_safe_flag_spec
     Linker flag (passed through the C compiler) used to generate
     thread-safe libraries.

 -- Variable: to_host_file_cmd
     If the toolchain is not native to the build platform (e.g. if you
     are using MSYS to drive the scripting, but are using the MinGW
     native Windows compiler) this variable describes how to convert
     file names from the format used by the build platform to the format
     used by host platform.  Normally set to 'func_convert_file_noop',
     libtool will autodetect most cases where other values should be
     used.  On rare occasions, it may be necessary to override the
     autodetected value (*note Cygwin to MinGW Cross::).

 -- Variable: to_tool_file_cmd
     If the toolchain is not native to the build platform (e.g. if you
     are using some Unix to drive the scripting together with a Windows
     toolchain running in Wine) this variable describes how to convert
     file names from the format used by the build platform to the format
     used by the toolchain.  Normally set to 'func_convert_file_noop'.

 -- Variable: version_type
     The library version numbering type.  One of 'libtool',
     'freebsd-aout', 'freebsd-elf', 'irix', 'linux', 'osf', 'sunos',
     'windows', or 'none'.

 -- Variable: want_nocaseglob
     Find potential files using the shell option 'nocaseglob', when
     'deplibs_check_method' is 'file_magic'.  Normally set to 'no'.  Set
     to 'yes' to enable the 'nocaseglob' shell option when looking for
     potential file names in a case-insensitive manner.

 -- Variable: whole_archive_flag_spec
     Compiler flag to generate shared objects from convenience archives.

 -- Variable: wl
     The C compiler flag that allows libtool to pass a flag directly to
     the linker.  Used as: '${wl}SOME-FLAG'.

   Variables ending in '_cmds' or '_eval' contain a '~'-separated list
of commands that are 'eval'ed one after another.  If any of the commands
return a nonzero exit status, libtool generally exits with an error
message.

   Variables ending in '_spec' are 'eval'ed before being used by
libtool.

