info libtool

15.4 `libtool` script contents

Since version 1.4, the libtool script is generated by configure (see section Configuring libtool). 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 (see section Configuring libtool):

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 (see section 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’ in order 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 in order 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 can not 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’ in order 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 which 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 (see section 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 in which other values should be used. On rare occasions, it may be necessary to override the autodetected value (see section 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 evaled 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 evaled before being used by libtool.

This document was generated on December 1, 2011 using texi2html 5.0.

15.4 libtool script contents

15.4 `libtool` script contents