File: libtool.info,  Node: Link mode,  Next: Execute mode,  Prev: Compile mode,  Up: Invoking libtool

4.2 Link mode
=============

“Link” mode links together object files (including library objects) to
form another library or to create an executable program.

   MODE-ARGS consist of a command using the C compiler to create an
output file (with the ‘-o’ flag) from several object files.

   The following components of MODE-ARGS are treated specially:

‘-all-static’
     If OUTPUT-FILE is a program, then do not link it against any shared
     libraries at all.  If OUTPUT-FILE is a library, then only create a
     static library.  In general, this flag cannot be used together with
     ‘disable-static’ (*note LT_INIT::).

‘-avoid-version’
     Tries to avoid versioning (*note Versioning::) for libraries and
     modules, i.e. no version information is stored and no symbolic
     links are created.  If the platform requires versioning, this
     option has no effect.

‘-bindir’
     Pass the absolute name of the directory for installing executable
     programs (*note Directory Variables: (standards)Directory
     Variables.).  ‘libtool’ may use this value to install shared
     libraries there on systems that do not provide for any library
     hardcoding and use the directory of a program and the ‘PATH’
     variable as library search path.  This is typically used for DLLs
     on Windows or other systems using the PE (Portable Executable)
     format.  On other systems, ‘-bindir’ is ignored.  The default value
     used is ‘LIBDIR/../bin’ for libraries installed to ‘LIBDIR’.  You
     should not use ‘-bindir’ for modules.

‘-dlopen FILE’
     Same as ‘-dlpreopen FILE’, if native dlopening is not supported on
     the host platform (*note Dlopened modules::) or if the program is
     linked with ‘-static’, ‘-static-libtool-libs’, or ‘-all-static’.
     Otherwise, no effect.  If FILE is ‘self’ Libtool will make sure
     that the program can ‘dlopen’ itself, either by enabling
     ‘-export-dynamic’ or by falling back to ‘-dlpreopen self’.

‘-dlpreopen FILE’
     Link FILE into the output program, and add its symbols to the list
     of preloaded symbols (*note Dlpreopening::).  If FILE is ‘self’,
     the symbols of the program itself will be added to preloaded symbol
     lists.  If FILE is ‘force’ Libtool will make sure that a preloaded
     symbol list is always _defined_, regardless of whether it's empty
     or not.

‘-export-dynamic’
     Allow symbols from OUTPUT-FILE to be resolved with ‘dlsym’ (*note
     Dlopened modules::).

‘-export-symbols SYMFILE’
     Tells the linker to export only the symbols listed in SYMFILE.  The
     symbol file should end in ‘.sym’ and must contain the name of one
     symbol per line.  This option has no effect:
        • on static libraries, and
        • on shared libraries on some platforms, such as AIX and Haiku.
     By default all symbols are exported.

‘-export-symbols-regex REGEX’
     Same as ‘-export-symbols’, except that only symbols matching the
     regular expression REGEX are exported.  By default all symbols are
     exported.

‘-LLIBDIR’
     Search LIBDIR for required libraries that have already been
     installed.

‘-lNAME’
     OUTPUT-FILE requires the installed library ‘libNAME’.  This option
     is required even when OUTPUT-FILE is not an executable.

‘-module’
     Creates a library that can be dlopened (*note Dlopened modules::).
     This option doesn't work for programs.  Module names don't need to
     be prefixed with ‘lib’.  In order to prevent name clashes, however,
     ‘libNAME’ and ‘NAME’ must not be used at the same time in your
     package.

‘-no-fast-install’
     Disable fast-install mode for the executable OUTPUT-FILE.  Useful
     if the program won't be necessarily installed.

‘-no-install’
     Link an executable OUTPUT-FILE that can't be installed and
     therefore doesn't need a wrapper script on systems that allow
     hardcoding of library paths.  Useful if the program is only used in
     the build tree, e.g., for testing or generating other files.

‘-no-undefined’
     Declare that OUTPUT-FILE does not depend on any libraries other
     than the ones listed on the command line, i.e., after linking, it
     will not have unresolved symbols.  Some platforms require all
     symbols in shared libraries to be resolved at library creation
     (*note Inter-library dependencies::), and using this parameter
     allows ‘libtool’ to assume that this will not happen.

‘-o OUTPUT-FILE’
     Create OUTPUT-FILE from the specified objects and libraries.

‘-objectlist FILE’
     Use a list of object files found in FILE to specify objects.

‘-os2dllname NAME’
     Use this to change the DLL base name on OS/2 to NAME, to keep
     within the 8 character base name limit on this system.

‘-precious-files-regex REGEX’
     Prevents removal of files from the temporary output directory whose
     names match this regular expression.  You might specify ‘\.bbg?$’
     to keep those files created with ‘gcc -ftest-coverage’ for example.

‘-release RELEASE’
     Specify that the library was generated by release RELEASE of your
     package, so that users can easily tell what versions are newer than
     others.  Be warned that no two releases of your package will be
     binary compatible if you use this flag.  If you want binary
     compatibility, use the ‘-version-info’ flag instead (*note
     Versioning::).

‘-rpath LIBDIR’
     If OUTPUT-FILE is a library, it will eventually be installed in
     LIBDIR.  If OUTPUT-FILE is a program, add LIBDIR to the run-time
     path of the program.  On platforms that don't support hardcoding
     library paths into executables and only search PATH for shared
     libraries, such as when OUTPUT-FILE is a Windows (or other PE
     platform) DLL, the ‘.la’ control file will be installed in LIBDIR,
     but see ‘-bindir’ above for the eventual destination of the ‘.dll’
     or other library file itself.

‘-R LIBDIR’
     If OUTPUT-FILE is a program, add LIBDIR to its run-time path.  If
     OUTPUT-FILE is a library, add ‘-RLIBDIR’ to its DEPENDENCY_LIBS, so
     that, whenever the library is linked into a program, LIBDIR will be
     added to its run-time path.

‘-shared’
     If OUTPUT-FILE is a program, then link it against any uninstalled
     shared libtool libraries (this is the default behavior).  If
     OUTPUT-FILE is a library, then only create a shared library.  In
     the later case, libtool will signal an error if it was configured
     with ‘--disable-shared’, or if the host does not support shared
     libraries.

‘-shrext SUFFIX’
     If OUTPUT-FILE is a libtool library, replace the system's standard
     file name extension for shared libraries with SUFFIX (most systems
     use ‘.so’ here).  This option is helpful in certain cases where an
     application requires that shared libraries (typically modules) have
     an extension other than the default one.  Please note you must
     supply the full file name extension including any leading dot.

‘-static’
     If OUTPUT-FILE is a program, then do not link it against any
     uninstalled shared libtool libraries.  If OUTPUT-FILE is a library,
     then only create a static library.

‘-static-libtool-libs’
     If OUTPUT-FILE is a program, then do not link it against any shared
     libtool libraries.  If OUTPUT-FILE is a library, then only create a
     static library.

‘-version-info CURRENT[:REVISION[:AGE]]’
     If OUTPUT-FILE is a libtool library, use interface version
     information CURRENT, REVISION, and AGE to build it (*note
     Versioning::).  Do *not* use this flag to specify package release
     information, rather see the ‘-release’ flag.

‘-version-number MAJOR[:MINOR[:REVISION]]’
     If OUTPUT-FILE is a libtool library, compute interface version
     information so that the resulting library uses the specified major,
     minor and revision numbers.  This is designed to permit libtool to
     be used with existing projects where identical version numbers are
     already used across operating systems.  New projects should use the
     ‘-version-info’ flag instead.

‘-weak LIBNAME’
     if OUTPUT-FILE is a libtool library, declare that it provides a
     weak LIBNAME interface.  This is a hint to libtool that there is no
     need to append LIBNAME to the list of dependency libraries of
     OUTPUT-FILE, because linking against OUTPUT-FILE already supplies
     the same interface (*note Linking with dlopened modules::).

‘-Wc,FLAG’
‘-Xcompiler FLAG’
     Pass a linker-specific flag directly to the compiler.  With ‘-Wc,’,
     multiple flags may be separated by commas, whereas ‘-Xcompiler ’
     passes through commas unchanged.

‘-Wa,FLAG’
‘-Xassembler FLAG’
     Pass a linker-specific flag directly to the assembler.  With
     ‘-Wa,’, multiple flags may be separated by commas, whereas
     ‘-Xassembler ’ passes through commas unchanged.

‘-Wl,FLAG’
‘-Xlinker FLAG’
     Pass a linker-specific flag directly to the linker.

‘-XCClinker FLAG’
     Pass a link-specific flag to the compiler driver (‘CC’) during
     linking.

   If the OUTPUT-FILE ends in ‘.la’, then a libtool library is created,
which must be built only from library objects (‘.lo’ files).  The
‘-rpath’ option is required.  In the current implementation, libtool
libraries may not depend on other uninstalled libtool libraries (*note
Inter-library dependencies::).

   If the OUTPUT-FILE ends in ‘.a’, then a standard library is created
using ‘ar’ and possibly ‘ranlib’.

   If OUTPUT-FILE ends in ‘.o’ or ‘.lo’, then a reloadable object file
is created from the input files (generally using ‘ld -r’).  This method
is often called “partial linking”.

   Otherwise, an executable program is created.