Go to the first, previous, next, last section, table of contents.


12. Maintenance notes for libtool

This chapter contains information that the libtool maintainer finds important. It will be of no use to you unless you are considering porting libtool to new systems, or writing your own libtool.

12.1 Porting libtool to new systems

To port libtool to a new system, you'll generally need the following information:

man pages for ld(1) and cc(1)
These generally describe what flags are used to generate PIC, to create shared libraries, and to link against only static libraries. You may need to follow some cross references to find the information that is required.
man pages for ld.so(8), rtld(8), or equivalent
These are a valuable resource for understanding how shared libraries are loaded on the system.
man page for ldconfig(8), or equivalent
This page usually describes how to install shared libraries.
output from ls -l /lib /usr/lib
This shows the naming convention for shared libraries on the system, including which names should be symbolic links.
any additional documentation
Some systems have special documentation on how to build and install shared libraries.

12.2 Tested platforms

This table describes when libtool was last known to be tested on platforms where it claims to support shared libraries:

--------------------------------------------------------
canonical host name          compiler  libtool   results
                                       release
--------------------------------------------------------
alpha-dec-osf3.2             cc        0.8       ok
alpha-dec-osf3.2             gcc       0.8       ok
alpha-dec-osf4.0             cc        1.0f      ok
alpha-dec-osf4.0             gcc       1.0f      ok
alpha-unknown-linux-gnu      gcc       0.9h      ok
hppa1.1-hp-hpux9.07          cc        1.0f      ok
hppa1.1-hp-hpux9.07          gcc       1.0f      ok
hppa1.1-hp-hpux10.10         cc        0.9h      ok
hppa1.1-hp-hpux10.10         gcc       0.9h      ok
i386-unknown-freebsd2.1.5    gcc       0.5       ok
i386-unknown-gnu0.0          gcc       0.5       ok
i386-unknown-netbsd1.2       gcc       0.9g      ok
i586-pc-linux-gnulibc1       gcc       1.0i      ok
i586-pc-linux-gnu            gcc       1.0i      ok
mips-sgi-irix5.2             gcc       1.0i      ok
mips-sgi-irix5.3             cc        0.8       ok
mips-sgi-irix5.3             gcc       0.8       ok
mips-sgi-irix6.2             cc        0.9       ok
mips-sgi-irix6.3             cc        1.0f      ok
mips-sgi-irix6.3             gcc       1.0i      ok
mips-sgi-irix6.3             irix5-gcc 1.0f      ok
mipsel-unknown-openbsd2.1    gcc       1.0       ok
powerpc-ibm-aix4.1.4.0       xlc       1.0i      ok
powerpc-ibm-aix4.1.4.0       gcc       1.0       ok
rs6000-ibm-aix3.2.5          xlc       1.0i      ok
rs6000-ibm-aix3.2.5          gcc       1.0i      ok*
sparc-sun-linux-gnu2.1.23    gcc       0.9h      ok
sparc-sun-sunos4.1.3         gcc       1.0i      ok
sparc-sun-sunos4.1.4         cc        1.0f      ok
sparc-sun-sunos4.1.4         gcc       1.0f      ok
sparc-sun-solaris2.4         cc        1.0a      ok
sparc-sun-solaris2.4         gcc       1.0a      ok
sparc-sun-solaris2.5         cc        1.0f      ok
sparc-sun-solaris2.5         gcc       1.0i      ok
sparc-sun-solaris2.6         gcc       1.0i      ok
--------------------------------------------------------

* Some versions of GCC's collect2 linker program cannot link trivial
static binaries on AIX 3.  For these configurations, libtool's `-static'
flag has no effect.

12.3 Platform quirks

This section is dedicated to the sanity of the libtool maintainer. It describes the programs that libtool uses, how they vary from system to system, and how to test for them.

Because libtool is a shell script, it is difficult to understand just by reading it from top to bottom. This section helps show why libtool does things a certain way. After reading it, then reading the scripts themselves, you should have a better sense of how to improve libtool, or write your own.

12.3.1 References

The following is a list of valuable documentation references:

12.3.2 Compilers

The only compiler characteristics that affect libtool are the flags needed (if any) to generate PIC objects. In general, if a C compiler supports certain PIC flags, then any derivative compilers support the same flags. Until there are some noteworthy exceptions to this rule, this section will document only C compilers.

The following C compilers have standard command line options, regardless of the platform:

gcc
This is the GNU C compiler, which is also the system compiler for many free operating systems (FreeBSD, GNU/Hurd, Linux/GNU, Lites, NetBSD, and OpenBSD, to name a few). The `-fpic' or `-fPIC' flags can be used to generate position-independent code. `-fPIC' is guaranteed to generate working code, but the code is slower on m68k, m88k, and Sparc chips. However, using `-fpic' on those chips imposes arbitrary size limits on the shared libraries.

The rest of this subsection lists compilers by the operating system that they are bundled with:

aix3*
aix4*
AIX compilers have no PIC flags, since AIX has been ported only to PowerPC and RS/6000 chips. (9)
hpux10*
Use `+Z' to generate PIC.
osf3*
Digital/UNIX 3.x does not have PIC flags, at least not on the PowerPC platform.
solaris2*
Use `-KPIC' to generate PIC.
sunos4*
Use `-PIC' to generate PIC.

12.3.3 Reloadable objects

On all known systems, a reloadable object can be created by running ld -r -o output.o input1.o input2.o. This reloadable object may be treated as exactly equivalent to other objects.

12.3.4 Archivers

On all known systems, building a static library can be accomplished by running ar cru libname.a obj1.o obj2.o ..., where the `.a' file is the output library, and each `.o' file is an object file.

On all known systems, if there is a program named ranlib, then it must be used to "bless" the created library before linking against it, with the ranlib libname.a command. Some systems, like Irix, use the ar ts command, instead.

12.4 libtool script contents

The libtool script is generated by ltconfig (see section 5.3 Configuring libtool). 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 and later inlines the contents of ltmain.sh into the generated libtool, which improves performance on many systems.

Here is a listing of each of the configuration variables, and how they are used within ltmain.sh:

Variable: AR
The name of the system library archiver.

Variable: CC
The name of the C compiler used to configure libtool.

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

Variable: LTCONFIG_VERSION
This is set to the version number of the ltconfig script, to prevent mismatches between the configuration information in libtool, and how that information is used in ltmain.sh.

Variable: NM
The name of a BSD-compatible nm program, which produces listings of global symbols in one the following formats:
address C global-variable-name
address D global-variable-name
address T global-function-name

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: archive_cmds
Variable: old_archive_cmds
Commands used to create shared and static libraries, respectively.

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: echo
An echo(1) program which does not interpret backslashes as an escape character.

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

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:
$ $NM | $global_symbol_pipe
symbol1 C-symbol1
symbol2 C-symbol2
symbol3 C-symbol3
...
$

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

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.

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.

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. Set to `unsupported' if directories specified by `$shlibpath_var' are searched at run time, but not at link time.

Variable: host
Variable: host_alias
For information purposes, set to the specified and canonical names of the system that libtool was configured for.

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_static_flag
Linker flag (passed through the C compiler) used to prevent dynamic linking.

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: 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: reload_cmds
Variable: reload_flag
Commands to create a reloadable object.

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

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: version_type
The library version numbering type. One of `libtool', `linux', `osf', `sunos', or `none'.

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

12.5 Cheap tricks

Here are a few tricks that you can use in order to make maintainership easier:


Go to the first, previous, next, last section, table of contents.