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