libtool: Link mode
1
1 4.2 Link mode
1 =============
1
1 "Link" mode links together object files (including library objects) to
1 form another library or to create an executable program.
1
1 MODE-ARGS consist of a command using the C compiler to create an
1 output file (with the '-o' flag) from several object files.
1
1 The following components of MODE-ARGS are treated specially:
1
1 '-all-static'
1 If OUTPUT-FILE is a program, then do not link it against any shared
1 libraries at all. If OUTPUT-FILE is a library, then only create a
1 static library. In general, this flag cannot be used together with
1 'disable-static' (⇒LT_INIT).
1
1 '-avoid-version'
1 Tries to avoid versioning (⇒Versioning) for libraries and
1 modules, i.e. no version information is stored and no symbolic
1 links are created. If the platform requires versioning, this
1 option has no effect.
1
1 '-bindir'
1 Pass the absolute name of the directory for installing executable
11 programs (⇒Directory Variables (standards)Directory
Variables.). 'libtool' may use this value to install shared
1 libraries there on systems that do not provide for any library
1 hardcoding and use the directory of a program and the 'PATH'
1 variable as library search path. This is typically used for DLLs
1 on Windows or other systems using the PE (Portable Executable)
1 format. On other systems, '-bindir' is ignored. The default value
1 used is 'LIBDIR/../bin' for libraries installed to 'LIBDIR'. You
1 should not use '-bindir' for modules.
1
1 '-dlopen FILE'
1 Same as '-dlpreopen FILE', if native dlopening is not supported on
1 the host platform (⇒Dlopened modules) or if the program is
1 linked with '-static', '-static-libtool-libs', or '-all-static'.
1 Otherwise, no effect. If FILE is 'self' Libtool will make sure
1 that the program can 'dlopen' itself, either by enabling
1 '-export-dynamic' or by falling back to '-dlpreopen self'.
1
1 '-dlpreopen FILE'
1 Link FILE into the output program, and add its symbols to the list
1 of preloaded symbols (⇒Dlpreopening). If FILE is 'self',
1 the symbols of the program itself will be added to preloaded symbol
1 lists. If FILE is 'force' Libtool will make sure that a preloaded
1 symbol list is always _defined_, regardless of whether it's empty
1 or not.
1
1 '-export-dynamic'
11 Allow symbols from OUTPUT-FILE to be resolved with 'dlsym' (⇒
Dlopened modules).
1
1 '-export-symbols SYMFILE'
1 Tells the linker to export only the symbols listed in SYMFILE. The
1 symbol file should end in '.sym' and must contain the name of one
1 symbol per line. This option has no effect on some platforms. By
1 default all symbols are exported.
1
1 '-export-symbols-regex REGEX'
1 Same as '-export-symbols', except that only symbols matching the
1 regular expression REGEX are exported. By default all symbols are
1 exported.
1
1 '-LLIBDIR'
1 Search LIBDIR for required libraries that have already been
1 installed.
1
1 '-lNAME'
1 OUTPUT-FILE requires the installed library 'libNAME'. This option
1 is required even when OUTPUT-FILE is not an executable.
1
1 '-module'
1 Creates a library that can be dlopened (⇒Dlopened modules).
1 This option doesn't work for programs. Module names don't need to
1 be prefixed with 'lib'. In order to prevent name clashes, however,
1 'libNAME' and 'NAME' must not be used at the same time in your
1 package.
1
1 '-no-fast-install'
1 Disable fast-install mode for the executable OUTPUT-FILE. Useful
1 if the program won't be necessarily installed.
1
1 '-no-install'
1 Link an executable OUTPUT-FILE that can't be installed and
1 therefore doesn't need a wrapper script on systems that allow
1 hardcoding of library paths. Useful if the program is only used in
1 the build tree, e.g., for testing or generating other files.
1
1 '-no-undefined'
1 Declare that OUTPUT-FILE does not depend on any libraries other
1 than the ones listed on the command line, i.e., after linking, it
1 will not have unresolved symbols. Some platforms require all
1 symbols in shared libraries to be resolved at library creation
1 (⇒Inter-library dependencies), and using this parameter
1 allows 'libtool' to assume that this will not happen.
1
1 '-o OUTPUT-FILE'
1 Create OUTPUT-FILE from the specified objects and libraries.
1
1 '-objectlist FILE'
1 Use a list of object files found in FILE to specify objects.
1
1 '-os2dllname NAME'
1 Use this to change the DLL base name on OS/2 to NAME, to keep
1 within the 8 character base name limit on this system.
1
1 '-precious-files-regex REGEX'
1 Prevents removal of files from the temporary output directory whose
1 names match this regular expression. You might specify '\.bbg?$'
1 to keep those files created with 'gcc -ftest-coverage' for example.
1
1 '-release RELEASE'
1 Specify that the library was generated by release RELEASE of your
1 package, so that users can easily tell what versions are newer than
1 others. Be warned that no two releases of your package will be
1 binary compatible if you use this flag. If you want binary
11 compatibility, use the '-version-info' flag instead (⇒
Versioning).
1
1 '-rpath LIBDIR'
1 If OUTPUT-FILE is a library, it will eventually be installed in
1 LIBDIR. If OUTPUT-FILE is a program, add LIBDIR to the run-time
1 path of the program. On platforms that don't support hardcoding
1 library paths into executables and only search PATH for shared
1 libraries, such as when OUTPUT-FILE is a Windows (or other PE
1 platform) DLL, the '.la' control file will be installed in LIBDIR,
1 but see '-bindir' above for the eventual destination of the '.dll'
1 or other library file itself.
1
1 '-R LIBDIR'
1 If OUTPUT-FILE is a program, add LIBDIR to its run-time path. If
1 OUTPUT-FILE is a library, add '-RLIBDIR' to its DEPENDENCY_LIBS, so
1 that, whenever the library is linked into a program, LIBDIR will be
1 added to its run-time path.
1
1 '-shared'
1 If OUTPUT-FILE is a program, then link it against any uninstalled
1 shared libtool libraries (this is the default behavior). If
1 OUTPUT-FILE is a library, then only create a shared library. In
1 the later case, libtool will signal an error if it was configured
1 with '--disable-shared', or if the host does not support shared
1 libraries.
1
1 '-shrext SUFFIX'
1 If OUTPUT-FILE is a libtool library, replace the system's standard
1 file name extension for shared libraries with SUFFIX (most systems
1 use '.so' here). This option is helpful in certain cases where an
1 application requires that shared libraries (typically modules) have
1 an extension other than the default one. Please note you must
1 supply the full file name extension including any leading dot.
1
1 '-static'
1 If OUTPUT-FILE is a program, then do not link it against any
1 uninstalled shared libtool libraries. If OUTPUT-FILE is a library,
1 then only create a static library.
1
1 '-static-libtool-libs'
1 If OUTPUT-FILE is a program, then do not link it against any shared
1 libtool libraries. If OUTPUT-FILE is a library, then only create a
1 static library.
1
1 '-version-info CURRENT[:REVISION[:AGE]]'
1 If OUTPUT-FILE is a libtool library, use interface version
11 information CURRENT, REVISION, and AGE to build it (⇒
Versioning). Do *not* use this flag to specify package release
1 information, rather see the '-release' flag.
1
1 '-version-number MAJOR[:MINOR[:REVISION]]'
1 If OUTPUT-FILE is a libtool library, compute interface version
1 information so that the resulting library uses the specified major,
1 minor and revision numbers. This is designed to permit libtool to
1 be used with existing projects where identical version numbers are
1 already used across operating systems. New projects should use the
1 '-version-info' flag instead.
1
1 '-weak LIBNAME'
1 if OUTPUT-FILE is a libtool library, declare that it provides a
1 weak LIBNAME interface. This is a hint to libtool that there is no
1 need to append LIBNAME to the list of dependency libraries of
1 OUTPUT-FILE, because linking against OUTPUT-FILE already supplies
1 the same interface (⇒Linking with dlopened modules).
1
1 '-Wc,FLAG'
1 '-Xcompiler FLAG'
1 Pass a linker-specific flag directly to the compiler. With '-Wc,',
1 multiple flags may be separated by commas, whereas '-Xcompiler '
1 passes through commas unchanged.
1
1 '-Wl,FLAG'
1 '-Xlinker FLAG'
1 Pass a linker-specific flag directly to the linker.
1
1 '-XCClinker FLAG'
1 Pass a link-specific flag to the compiler driver ('CC') during
1 linking.
1
1 If the OUTPUT-FILE ends in '.la', then a libtool library is created,
1 which must be built only from library objects ('.lo' files). The
1 '-rpath' option is required. In the current implementation, libtool
11 libraries may not depend on other uninstalled libtool libraries (⇒
Inter-library dependencies).
1
1 If the OUTPUT-FILE ends in '.a', then a standard library is created
1 using 'ar' and possibly 'ranlib'.
1
1 If OUTPUT-FILE ends in '.o' or '.lo', then a reloadable object file
1 is created from the input files (generally using 'ld -r'). This method
1 is often called "partial linking".
1
1 Otherwise, an executable program is created.
1