libtool: libtool script contents
1
1 15.4 'libtool' script contents
1 ==============================
1
1 Since version 1.4, the 'libtool' script is generated by 'configure'
1 (⇒Configuring). In earlier versions, 'configure' achieved this
1 by calling a helper script called 'ltconfig'. From libtool version 0.7
1 to 1.0, this script simply set shell variables, then sourced the libtool
1 backend, 'ltmain.sh'. 'ltconfig' from libtool version 1.1 through 1.3
1 inlined the contents of 'ltmain.sh' into the generated 'libtool', which
1 improved performance on many systems. The tests that 'ltconfig' used to
1 perform are now kept in 'libtool.m4' where they can be written using
1 Autoconf. This has the runtime performance benefits of inlined
1 'ltmain.sh', _and_ improves the build time a little while considerably
1 easing the amount of raw shell code that used to need maintaining.
1
1 The convention used for naming variables that hold shell commands for
1 delayed evaluation, is to use the suffix '_cmd' where a single line of
1 valid shell script is needed, and the suffix '_cmds' where multiple
1 lines of shell script *may* be delayed for later evaluation. By
1 convention, '_cmds' variables delimit the evaluation units with the '~'
1 character where necessary.
1
1 Here is a listing of each of the configuration variables, and how
1 they are used within 'ltmain.sh' (⇒Configuring):
1
1 -- Variable: AR
1 The name of the system library archiver.
1
1 -- Variable: CC
1 The name of the compiler used to configure libtool. This will
11 always contain the compiler for the current language (⇒
Tags).
1
1 -- Variable: ECHO
1 An 'echo' program that does not interpret backslashes as an escape
1 character. It may be given only one argument, so due quoting is
1 necessary.
1
1 -- Variable: LD
1 The name of the linker that libtool should use internally for
1 reloadable linking and possibly shared libraries.
1
1 -- Variable: LTCC
1 -- Variable: LTCFLAGS
1 The name of the C compiler and C compiler flags used to configure
1 libtool.
1
1 -- Variable: NM
1 The name of a BSD- or MS-compatible program that produces listings
1 of global symbols. For BSD 'nm', the symbols should be in one the
1 following formats:
1
1 ADDRESS C GLOBAL-VARIABLE-NAME
1 ADDRESS D GLOBAL-VARIABLE-NAME
1 ADDRESS T GLOBAL-FUNCTION-NAME
1
1 For MS 'dumpbin', the symbols should be in one of the following
1 formats:
1
1 COUNTER SIZE UNDEF notype External | GLOBAL-VAR
1 COUNTER ADDRESS SECTION notype External | GLOBAL-VAR
1 COUNTER ADDRESS SECTION notype () External | GLOBAL-FUNC
1
1 The SIZE of the global variables are not zero and the SECTION of
1 the global functions are not "UNDEF". Symbols in "pick any"
1 sections ("pick any" appears in the section header) are not global
1 either.
1
1 -- Variable: RANLIB
1 Set to the name of the 'ranlib' program, if any.
1
1 -- Variable: allow_undefined_flag
1 The flag that is used by 'archive_cmds' to declare that there will
1 be unresolved symbols in the resulting shared library. Empty, if
1 no such flag is required. Set to 'unsupported' if there is no way
1 to generate a shared library with references to symbols that aren't
1 defined in that library.
1
1 -- Variable: always_export_symbols
1 Whether libtool should automatically generate a list of exported
1 symbols using 'export_symbols_cmds' before linking an archive. Set
1 to 'yes' or 'no'. Default is 'no'.
1
1 -- Variable: archive_cmds
1 -- Variable: archive_expsym_cmds
1 -- Variable: old_archive_cmds
1 Commands used to create shared libraries, shared libraries with
1 '-export-symbols' and static libraries, respectively.
1
1 -- Variable: archiver_list_spec
1 Specify filename containing input files for 'AR'.
1
1 -- Variable: old_archive_from_new_cmds
1 If the shared library depends on a static library,
1 'old_archive_from_new_cmds' contains the commands used to create
1 that static library. If this variable is not empty,
1 'old_archive_cmds' is not used.
1
1 -- Variable: old_archive_from_expsyms_cmds
1 If a static library must be created from the export symbol list to
1 correctly link with a shared library,
1 'old_archive_from_expsyms_cmds' contains the commands needed to
1 create that static library. When these commands are executed, the
1 variable 'soname' contains the name of the shared library in
1 question, and the '$objdir/$newlib' contains the path of the static
1 library these commands should build. After executing these
1 commands, libtool will proceed to link against '$objdir/$newlib'
1 instead of 'soname'.
1
1 -- Variable: lock_old_archive_extraction
1 Set to 'yes' if the extraction of a static library requires locking
1 the library file. This is required on Darwin.
1
1 -- Variable: build
1 -- Variable: build_alias
1 -- Variable: build_os
1 Set to the specified and canonical names of the system that libtool
1 was built on.
1
1 -- Variable: build_libtool_libs
1 Whether libtool should build shared libraries on this system. Set
1 to 'yes' or 'no'.
1
1 -- Variable: build_old_libs
1 Whether libtool should build static libraries on this system. Set
1 to 'yes' or 'no'.
1
1 -- Variable: compiler_c_o
1 Whether the compiler supports the '-c' and '-o' options
1 simultaneously. Set to 'yes' or 'no'.
1
1 -- Variable: compiler_needs_object
1 Whether the compiler has to see an object listed on the command
1 line in order to successfully invoke the linker. If 'no', then a
1 set of convenience archives or a set of object file names can be
1 passed via linker-specific options or linker scripts.
1
1 -- Variable: dlopen_support
1 Whether 'dlopen' is supported on the platform. Set to 'yes' or
1 'no'.
1
1 -- Variable: dlopen_self
1 Whether it is possible to 'dlopen' the executable itself. Set to
1 'yes' or 'no'.
1
1 -- Variable: dlopen_self_static
1 Whether it is possible to 'dlopen' the executable itself, when it
1 is linked statically ('-all-static'). Set to 'yes' or 'no'.
1
1 -- Variable: exclude_expsyms
1 List of symbols that should not be listed in the preloaded symbols.
1
1 -- Variable: export_dynamic_flag_spec
1 Compiler link flag that allows a dlopened shared library to
1 reference symbols that are defined in the program.
1
1 -- Variable: export_symbols_cmds
1 Commands to extract exported symbols from 'libobjs' to the file
1 'export_symbols'.
1
1 -- Variable: extract_expsyms_cmds
1 Commands to extract the exported symbols list from a shared
1 library. These commands are executed if there is no file
1 '$objdir/$soname-def', and should write the names of the exported
1 symbols to that file, for the use of
1 'old_archive_from_expsyms_cmds'.
1
1 -- Variable: fast_install
1 Determines whether libtool will privilege the installer or the
1 developer. The assumption is that installers will seldom run
1 programs in the build tree, and the developer will seldom install.
1 This is only meaningful on platforms where
1 'shlibpath_overrides_runpath' is not 'yes', so 'fast_install' will
1 be set to 'needless' in this case. If 'fast_install' set to 'yes',
1 libtool will create programs that search for installed libraries,
1 and, if a program is run in the build tree, a new copy will be
1 linked on-demand to use the yet-to-be-installed libraries. If set
1 to 'no', libtool will create programs that use the
1 yet-to-be-installed libraries, and will link a new copy of the
1 program at install time. The default value is 'yes' or 'needless',
1 depending on platform and configuration flags, and it can be turned
1 from 'yes' to 'no' with the configure flag
1 '--disable-fast-install'.
1
1 On some systems, the linker always hardcodes paths to dependent
1 libraries into the output. In this case, 'fast_install' is never
1 set to 'yes', and relinking at install time is triggered. This
1 also means that 'DESTDIR' installation does not work as expected.
1
1 -- Variable: file_magic_glob
1 How to find potential files when 'deplibs_check_method' is
1 'file_magic'. 'file_magic_glob' is a 'sed' expression, and the
1 'sed' instance is fed potential file names that are transformed by
1 the 'file_magic_glob' expression. Useful when the shell does not
1 support the shell option 'nocaseglob', making 'want_nocaseglob'
1 inappropriate. Normally disabled (i.e. 'file_magic_glob' is
1 empty).
1
1 -- Variable: finish_cmds
1 Commands to tell the dynamic linker how to find shared libraries in
1 a specific directory.
1
1 -- Variable: finish_eval
1 Same as 'finish_cmds', except the commands are not displayed.
1
1 -- Variable: global_symbol_pipe
1 A pipeline that takes the output of 'NM', and produces a listing of
1 raw symbols followed by their C names. For example:
1
1 $ eval "$NM progname | $global_symbol_pipe"
1 D SYMBOL1 C-SYMBOL1
1 T SYMBOL2 C-SYMBOL2
1 C SYMBOL3 C-SYMBOL3
1 ...
1 $
1
1 The first column contains the symbol type (used to tell data from
1 code) but its meaning is system dependent.
1
1 -- Variable: global_symbol_to_cdecl
1 A pipeline that translates the output of 'global_symbol_pipe' into
1 proper C declarations. Since some platforms, such as HP/UX, have
1 linkers that differentiate code from data, data symbols are
1 declared as data, and code symbols are declared as functions.
1
1 -- Variable: hardcode_action
1 Either 'immediate' or 'relink', depending on whether shared library
1 paths can be hardcoded into executables before they are installed,
1 or if they need to be relinked.
1
1 -- Variable: hardcode_direct
1 Set to 'yes' or 'no', depending on whether the linker hardcodes
1 directories if a library is directly specified on the command line
1 (such as 'DIR/libNAME.a') when 'hardcode_libdir_flag_spec' is
1 specified.
1
1 -- Variable: hardcode_direct_absolute
1 Some architectures hardcode "absolute" library directories that
1 cannot be overridden by 'shlibpath_var' when 'hardcode_direct' is
1 'yes'. In that case set 'hardcode_direct_absolute' to 'yes', or
1 otherwise 'no'.
1
1 -- Variable: hardcode_into_libs
1 Whether the platform supports hardcoding of run-paths into
1 libraries. If enabled, linking of programs will be much simpler
1 but libraries will need to be relinked during installation. Set to
1 'yes' or 'no'.
1
1 -- Variable: hardcode_libdir_flag_spec
1 Flag to hardcode a 'libdir' variable into a binary, so that the
1 dynamic linker searches 'libdir' for shared libraries at runtime.
1 If it is empty, libtool will try to use some other hardcoding
1 mechanism.
1
1 -- Variable: hardcode_libdir_separator
1 If the compiler only accepts a single 'hardcode_libdir_flag', then
1 this variable contains the string that should separate multiple
1 arguments to that flag.
1
1 -- Variable: hardcode_minus_L
1 Set to 'yes' or 'no', depending on whether the linker hardcodes
1 directories specified by '-L' flags into the resulting executable
1 when 'hardcode_libdir_flag_spec' is specified.
1
1 -- Variable: hardcode_shlibpath_var
1 Set to 'yes' or 'no', depending on whether the linker hardcodes
1 directories by writing the contents of '$shlibpath_var' into the
1 resulting executable when 'hardcode_libdir_flag_spec' is specified.
1 Set to 'unsupported' if directories specified by '$shlibpath_var'
1 are searched at run time, but not at link time.
1
1 -- Variable: host
1 -- Variable: host_alias
1 -- Variable: host_os
1 Set to the specified and canonical names of the system that libtool
1 was configured for.
1
1 -- Variable: include_expsyms
1 List of symbols that must always be exported when using
1 'export_symbols'.
1
1 -- Variable: inherit_rpath
1 Whether the linker adds runtime paths of dependency libraries to
1 the runtime path list, requiring libtool to relink the output when
1 installing. Set to 'yes' or 'no'. Default is 'no'.
1
1 -- Variable: install_override_mode
1 Permission mode override for installation of shared libraries. If
1 the runtime linker fails to load libraries with wrong permissions,
1 then it may fail to execute programs that are needed during
1 installation, because these need the library that has just been
1 installed. In this case, it is necessary to pass the mode to
1 'install' with '-m INSTALL_OVERRIDE_MODE'.
1
1 -- Variable: libext
1 The standard old archive suffix (normally 'a').
1
1 -- Variable: libname_spec
1 The format of a library name prefix. On all Unix systems, static
1 libraries are called 'libNAME.a', but on some systems (such as OS/2
1 or MS-DOS), the library is just called 'NAME.a'.
1
1 -- Variable: library_names_spec
1 A list of shared library names. The first is the name of the file,
1 the rest are symbolic links to the file. The name in the list is
1 the file name that the linker finds when given '-lNAME'.
1
1 -- Variable: link_all_deplibs
1 Whether libtool must link a program against all its dependency
1 libraries. Set to 'yes' or 'no'. Default is 'unknown', which is a
1 synonym for 'yes'.
1
1 -- Variable: link_static_flag
1 Linker flag (passed through the C compiler) used to prevent dynamic
1 linking.
1
1 -- Variable: macro_version
1 -- Variable: macro_revision
1 The release and revision from which the libtool.m4 macros were
1 taken. This is used to ensure that macros and 'ltmain.sh'
1 correspond to the same Libtool version.
1
1 -- Variable: max_cmd_len
1 The approximate longest command line that can be passed to '$SHELL'
1 without being truncated, as computed by 'LT_CMD_MAX_LEN'.
1
1 -- Variable: need_lib_prefix
1 Whether we can 'dlopen' modules without a 'lib' prefix. Set to
1 'yes' or 'no'. By default, it is 'unknown', which means the same
1 as 'yes', but documents that we are not really sure about it. 'no'
1 means that it is possible to 'dlopen' a module without the 'lib'
1 prefix.
1
1 -- Variable: need_version
1 Whether versioning is required for libraries, i.e. whether the
1 dynamic linker requires a version suffix for all libraries. Set to
1 'yes' or 'no'. By default, it is 'unknown', which means the same
1 as 'yes', but documents that we are not really sure about it.
1
1 -- Variable: need_locks
1 Whether files must be locked to prevent conflicts when compiling
1 simultaneously. Set to 'yes' or 'no'.
1
1 -- Variable: nm_file_list_spec
1 Specify filename containing input files for 'NM'.
1
1 -- Variable: no_builtin_flag
1 Compiler flag to disable builtin functions that conflict with
1 declaring external global symbols as 'char'.
1
1 -- Variable: no_undefined_flag
1 The flag that is used by 'archive_cmds' to declare that there will
1 be no unresolved symbols in the resulting shared library. Empty,
1 if no such flag is required.
1
1 -- Variable: objdir
1 The name of the directory that contains temporary libtool files.
1
1 -- Variable: objext
1 The standard object file suffix (normally 'o').
1
1 -- Variable: pic_flag
1 Any additional compiler flags for building library object files.
1
1 -- Variable: postinstall_cmds
1 -- Variable: old_postinstall_cmds
1 Commands run after installing a shared or static library,
1 respectively.
1
1 -- Variable: postuninstall_cmds
1 -- Variable: old_postuninstall_cmds
1 Commands run after uninstalling a shared or static library,
1 respectively.
1
1 -- Variable: postlink_cmds
1 Commands necessary for finishing linking programs. 'postlink_cmds'
1 are executed immediately after the program is linked. Any
1 occurrence of the string '@OUTPUT@' in 'postlink_cmds' is replaced
1 by the name of the created executable (i.e. not the wrapper, if a
1 wrapper is generated) prior to execution. Similarly,
1 '@TOOL_OUTPUT@' is replaced by the toolchain format of '@OUTPUT@'.
1 Normally disabled (i.e. 'postlink_cmds' empty).
1
1 -- Variable: reload_cmds
1 -- Variable: reload_flag
1 Commands to create a reloadable object. Set 'reload_cmds' to
1 'false' on systems that cannot create reloadable objects.
1
1 -- Variable: runpath_var
1 The environment variable that tells the linker what directories to
1 hardcode in the resulting executable.
1
1 -- Variable: shlibpath_overrides_runpath
1 Indicates whether it is possible to override the hard-coded library
1 search path of a program with an environment variable. If this is
1 set to no, libtool may have to create two copies of a program in
1 the build tree, one to be installed and one to be run in the build
1 tree only. When each of these copies is created depends on the
1 value of 'fast_install'. The default value is 'unknown', which is
1 equivalent to 'no'.
1
1 -- Variable: shlibpath_var
1 The environment variable that tells the dynamic linker where to
1 find shared libraries.
1
1 -- Variable: soname_spec
1 The name coded into shared libraries, if different from the real
1 name of the file.
1
1 -- Variable: striplib
1 -- Variable: old_striplib
1 Command to strip a shared ('striplib') or static ('old_striplib')
1 library, respectively. If these variables are empty, the strip
11 flag in the install mode will be ignored for libraries (⇒
Install mode).
1
1 -- Variable: sys_lib_dlsearch_path_spec
1 Expression to get the run-time system library search path.
1 Directories that appear in this list are never hard-coded into
1 executables.
1
1 -- Variable: sys_lib_search_path_spec
1 Expression to get the compile-time system library search path.
1 This variable is used by libtool when it has to test whether a
1 certain library is shared or static. The directories listed in
1 'shlibpath_var' are automatically appended to this list, every time
1 libtool runs (i.e., not at configuration time), because some
1 linkers use this variable to extend the library search path.
1 Linker switches such as '-L' also augment the search path.
1
1 -- Variable: thread_safe_flag_spec
1 Linker flag (passed through the C compiler) used to generate
1 thread-safe libraries.
1
1 -- Variable: to_host_file_cmd
1 If the toolchain is not native to the build platform (e.g. if you
1 are using MSYS to drive the scripting, but are using the MinGW
1 native Windows compiler) this variable describes how to convert
1 file names from the format used by the build platform to the format
1 used by host platform. Normally set to 'func_convert_file_noop',
1 libtool will autodetect most cases where other values should be
1 used. On rare occasions, it may be necessary to override the
1 autodetected value (⇒Cygwin to MinGW Cross).
1
1 -- Variable: to_tool_file_cmd
1 If the toolchain is not native to the build platform (e.g. if you
1 are using some Unix to drive the scripting together with a Windows
1 toolchain running in Wine) this variable describes how to convert
1 file names from the format used by the build platform to the format
1 used by the toolchain. Normally set to 'func_convert_file_noop'.
1
1 -- Variable: version_type
1 The library version numbering type. One of 'libtool',
1 'freebsd-aout', 'freebsd-elf', 'irix', 'linux', 'osf', 'sunos',
1 'windows', or 'none'.
1
1 -- Variable: want_nocaseglob
1 Find potential files using the shell option 'nocaseglob', when
1 'deplibs_check_method' is 'file_magic'. Normally set to 'no'. Set
1 to 'yes' to enable the 'nocaseglob' shell option when looking for
1 potential file names in a case-insensitive manner.
1
1 -- Variable: whole_archive_flag_spec
1 Compiler flag to generate shared objects from convenience archives.
1
1 -- Variable: wl
1 The C compiler flag that allows libtool to pass a flag directly to
1 the linker. Used as: '${wl}SOME-FLAG'.
1
1 Variables ending in '_cmds' or '_eval' contain a '~'-separated list
1 of commands that are 'eval'ed one after another. If any of the commands
1 return a nonzero exit status, libtool generally exits with an error
1 message.
1
1 Variables ending in '_spec' are 'eval'ed before being used by
1 libtool.
1