Next: Directory Options, Previous: Assembler Options, Up: Invoking GCC

### 3.15 Options for Linking

These options come into play when the compiler links object files into an executable output file. They are meaningless if the compiler is not doing a link step.

object-file-name
  A file name that does not end in a special recognized suffix is considered to name an object file or library. (Object files are distinguished from libraries by the linker according to the file contents.) If linking is done, these object files are used as input to the linker.
`-c`
`-S`
`-E`
  If any of these options is used, then the linker is not run, and object file names should not be used as arguments. See Overall Options.
`-flinker-output=`type
  This option controls code generation of the link-time optimizer. By default the linker output is automatically determined by the linker plugin. For debugging the compiler and if incremental linking with a non-LTO object file is desired, it may be useful to control the type manually.

  If type is ``exec`', code generation produces a static binary. In this case `-fpic` and `-fpie` are both disabled.

  If type is ``dyn`', code generation produces a shared library. In this case `-fpic` or `-fPIC` is preserved, but not enabled automatically. This allows to build shared libraries without position-independent code on architectures where this is possible, i.e. on x86.

  If type is ``pie`', code generation produces an `-fpie` executable. This results in similar optimizations as ``exec`' except that `-fpie` is not disabled if specified at compilation time.

  If type is ``rel`', the compiler assumes that incremental linking is done. The sections containing intermediate code for link-time optimization are merged, pre-optimized, and output to the resulting object file. In addition, if `-ffat-lto-objects` is specified, binary code is produced for future non-LTO linking. The object file produced by incremental linking is smaller than a static library produced from the same object files. At link time the result of incremental linking also loads faster than a static library assuming that the majority of objects in the library are used.

  Finally ``nolto-rel`' configures the compiler for incremental linking where code generation is forced, a final binary is produced, and the intermediate code for later link-time optimization is stripped. When multiple object files are linked together the resulting code is better optimized than with link-time optimizations disabled (for example, cross-module inlining happens), but most of benefits of whole program optimizations are lost.

  During the incremental link (by `-r`) the linker plugin defaults to `rel`. With current interfaces to GNU Binutils it is however not possible to incrementally link LTO objects and non-LTO objects into a single mixed object file. If any of object files in incremental link cannot be used for link-time optimization, the linker plugin issues a warning and uses ``nolto-rel`'. To maintain whole program optimization, it is recommended to link such objects into static library instead. Alternatively it is possible to use H.J. Lu's binutils with support for mixed objects.

`-fuse-ld=bfd`
  Use the `bfd` linker instead of the default linker.
`-fuse-ld=gold`
  Use the `gold` linker instead of the default linker.
`-fuse-ld=lld`
  Use the LLVM `lld` linker instead of the default linker.
`-fuse-ld=mold`
  Use the Modern Linker (`mold`) instead of the default linker.

`-l` library
`-l` library
  Search the library named library when linking. (The second alternative with the library as a separate argument is only for POSIX compliance and is not recommended.)

  The `-l` option is passed directly to the linker by GCC. Refer to your linker documentation for exact details. The general description below applies to the GNU linker.

  The linker searches a standard list of directories for the library. The directories searched include several standard system directories plus any that you specify with `-L`.

  Static libraries are archives of object files, and have file names like `liblibrary.a`. Some targets also support shared libraries, which typically have names like `liblibrary.so`. If both static and shared libraries are found, the linker gives preference to linking with the shared library unless the `-static` option is used.

  It makes a difference where in the command you write this option; the linker searches and processes libraries and object files in the order they are specified. Thus, ``foo.o -lz bar.o`' searches library ``z`' after file `foo.o` but before `bar.o`. If `bar.o` refers to functions in ``z`', those functions may not be loaded.

`-lobjc`
  You need this special case of the `-l` option in order to link an Objective-C or Objective-C++ program.
`-nostartfiles`
  Do not use the standard system startup files when linking. The standard system libraries are used normally, unless `-nostdlib`, `-nolibc`, or `-nodefaultlibs` is used.
`-nodefaultlibs`
  Do not use the standard system libraries when linking. Only the libraries you specify are passed to the linker, and options specifying linkage of the system libraries, such as `-static-libgcc` or `-shared-libgcc`, are ignored. The standard startup files are used normally, unless `-nostartfiles` is used.

  The compiler may generate calls to `memcmp`, `memset`, `memcpy` and `memmove`. These entries are usually resolved by entries in libc. These entry points should be supplied through some other mechanism when this option is specified.

`-nolibc`
  Do not use the C library or system libraries tightly coupled with it when linking. Still link with the startup files, `libgcc` or toolchain provided language support libraries such as `libgnat`, `libgfortran` or `libstdc++` unless options preventing their inclusion are used as well. This typically removes `-lc` from the link command line, as well as system libraries that normally go with it and become meaningless when absence of a C library is assumed, for example `-lpthread` or `-lm` in some configurations. This is intended for bare-board targets when there is indeed no C library available.
`-nostdlib`
  Do not use the standard system startup files or libraries when linking. No startup files and only the libraries you specify are passed to the linker, and options specifying linkage of the system libraries, such as `-static-libgcc` or `-shared-libgcc`, are ignored.

  The compiler may generate calls to `memcmp`, `memset`, `memcpy` and `memmove`. These entries are usually resolved by entries in libc. These entry points should be supplied through some other mechanism when this option is specified.

  One of the standard libraries bypassed by `-nostdlib` and `-nodefaultlibs` is `libgcc.a`, a library of internal subroutines which GCC uses to overcome shortcomings of particular machines, or special needs for some languages. (See Interfacing to GCC Output, for more discussion of `libgcc.a`.) In most cases, you need `libgcc.a` even when you want to avoid other standard libraries. In other words, when you specify `-nostdlib` or `-nodefaultlibs` you should usually specify `-lgcc` as well. This ensures that you have no unresolved references to internal GCC library subroutines. (An example of such an internal subroutine is `__main`, used to ensure C++ constructors are called; see `collect2`.)

`-e` entry
`--entry=`entry
  Specify that the program entry point is entry. The argument is interpreted by the linker; the GNU linker accepts either a symbol name or an address.
`-pie`
  Produce a dynamically linked position independent executable on targets that support it. For predictable results, you must also specify the same set of options used for compilation (`-fpie`, `-fPIE`, or model suboptions) when you specify this linker option.
`-no-pie`
  Don't produce a dynamically linked position independent executable.
`-static-pie`
  Produce a static position independent executable on targets that support it. A static position independent executable is similar to a static executable, but can be loaded at any address without a dynamic linker. For predictable results, you must also specify the same set of options used for compilation (`-fpie`, `-fPIE`, or model suboptions) when you specify this linker option.
`-pthread`
  Link with the POSIX threads library. This option is supported on GNU/Linux targets, most other Unix derivatives, and also on x86 Cygwin and MinGW targets. On some targets this option also sets flags for the preprocessor, so it should be used consistently for both compilation and linking.
`-r`
  Produce a relocatable object as output. This is also known as partial linking.
`-rdynamic`
  Pass the flag `-export-dynamic` to the ELF linker, on targets that support it. This instructs the linker to add all symbols, not only used ones, to the dynamic symbol table. This option is needed for some uses of `dlopen` or to allow obtaining backtraces from within a program.
`-s`
  Remove all symbol table and relocation information from the executable.
`-static`
  On systems that support dynamic linking, this overrides `-pie` and prevents linking with the shared libraries. On other systems, this option has no effect.
`-shared`
  Produce a shared object which can then be linked with other objects to form an executable. Not all systems support this option. For predictable results, you must also specify the same set of options used for compilation (`-fpic`, `-fPIC`, or model suboptions) when you specify this linker option.1
`-shared-libgcc`
`-static-libgcc`
  On systems that provide `libgcc` as a shared library, these options force the use of either the shared or static version, respectively. If no shared version of `libgcc` was built when the compiler was configured, these options have no effect.

  There are several situations in which an application should use the shared `libgcc` instead of the static version. The most common of these is when the application wishes to throw and catch exceptions across different shared libraries. In that case, each of the libraries as well as the application itself should use the shared `libgcc`.

  Therefore, the G++ driver automatically adds `-shared-libgcc` whenever you build a shared library or a main executable, because C++ programs typically use exceptions, so this is the right thing to do.

  If, instead, you use the GCC driver to create shared libraries, you may find that they are not always linked with the shared `libgcc`. If GCC finds, at its configuration time, that you have a non-GNU linker or a GNU linker that does not support option `--eh-frame-hdr`, it links the shared version of `libgcc` into shared libraries by default. Otherwise, it takes advantage of the linker and optimizes away the linking with the shared version of `libgcc`, linking with the static version of libgcc by default. This allows exceptions to propagate through such shared libraries, without incurring relocation costs at library load time.

  However, if a library or main executable is supposed to throw or catch exceptions, you must link it using the G++ driver, or using the option `-shared-libgcc`, such that it is linked with the shared `libgcc`.

`-static-libasan`
  When the `-fsanitize=address` option is used to link a program, the GCC driver automatically links against `libasan`. If `libasan` is available as a shared library, and the `-static` option is not used, then this links against the shared version of `libasan`. The `-static-libasan` option directs the GCC driver to link `libasan` statically, without necessarily linking other libraries statically.
`-static-libtsan`
  When the `-fsanitize=thread` option is used to link a program, the GCC driver automatically links against `libtsan`. If `libtsan` is available as a shared library, and the `-static` option is not used, then this links against the shared version of `libtsan`. The `-static-libtsan` option directs the GCC driver to link `libtsan` statically, without necessarily linking other libraries statically.
`-static-liblsan`
  When the `-fsanitize=leak` option is used to link a program, the GCC driver automatically links against `liblsan`. If `liblsan` is available as a shared library, and the `-static` option is not used, then this links against the shared version of `liblsan`. The `-static-liblsan` option directs the GCC driver to link `liblsan` statically, without necessarily linking other libraries statically.
`-static-libubsan`
  When the `-fsanitize=undefined` option is used to link a program, the GCC driver automatically links against `libubsan`. If `libubsan` is available as a shared library, and the `-static` option is not used, then this links against the shared version of `libubsan`. The `-static-libubsan` option directs the GCC driver to link `libubsan` statically, without necessarily linking other libraries statically.
`-static-libstdc++`
  When the `g++` program is used to link a C++ program, it normally automatically links against `libstdc++`. If `libstdc++` is available as a shared library, and the `-static` option is not used, then this links against the shared version of `libstdc++`. That is normally fine. However, it is sometimes useful to freeze the version of `libstdc++` used by the program without going all the way to a fully static link. The `-static-libstdc++` option directs the `g++` driver to link `libstdc++` statically, without necessarily linking other libraries statically.
`-symbolic`
  Bind references to global symbols when building a shared object. Warn about any unresolved references (unless overridden by the link editor option `-Xlinker -z -Xlinker defs`). Only a few systems support this option.
`-T` script
  Use script as the linker script. This option is supported by most systems using the GNU linker. On some targets, such as bare-board targets without an operating system, the `-T` option may be required when linking to avoid references to undefined symbols.
`-Xlinker` option
  Pass option as an option to the linker. You can use this to supply system-specific linker options that GCC does not recognize.

  If you want to pass an option that takes a separate argument, you must use `-Xlinker` twice, once for the option and once for the argument. For example, to pass `-assert definitions`, you must write `-Xlinker -assert -Xlinker definitions`. It does not work to write `-Xlinker "-assert definitions"`, because this passes the entire string as a single argument, which is not what the linker expects.

  When using the GNU linker, it is usually more convenient to pass arguments to linker options using the `option=value` syntax than as separate arguments. For example, you can specify `-Xlinker -Map=output.map` rather than `-Xlinker -Map -Xlinker output.map`. Other linkers may not support this syntax for command-line options.

`-Wl,`option
  Pass option as an option to the linker. If option contains commas, it is split into multiple options at the commas. You can use this syntax to pass an argument to the option. For example, `-Wl,-Map,output.map` passes `-Map output.map` to the linker. When using the GNU linker, you can also get the same effect with `-Wl,-Map=output.map`.
`-u` symbol
  Pretend the symbol symbol is undefined, to force linking of library modules to define it. You can use `-u` multiple times with different symbols to force loading of additional library modules.
`-z` keyword
  `-z` is passed directly on to the linker along with the keyword keyword. See the section in the documentation of your linker for permitted values and their meanings.

#### Footnotes

[1] On some systems, ``gcc -shared`' needs to build supplementary stub code for constructors to work. On multi-libbed systems, ``gcc -shared`' must select the correct support libraries to link against. Failing to supply the correct flags may lead to subtle defects. Supplying them in cases where they are not necessary is innocuous.