gcc: Link Options
1
1 3.14 Options for Linking
1 ========================
1
1 These options come into play when the compiler links object files into
1 an executable output file. They are meaningless if the compiler is not
1 doing a link step.
1
1 'OBJECT-FILE-NAME'
1 A file name that does not end in a special recognized suffix is
1 considered to name an object file or library. (Object files are
1 distinguished from libraries by the linker according to the file
1 contents.) If linking is done, these object files are used as
1 input to the linker.
1
1 '-c'
1 '-S'
1 '-E'
1 If any of these options is used, then the linker is not run, and
11 object file names should not be used as arguments. ⇒Overall
Options.
1
1 '-fuse-ld=bfd'
1 Use the 'bfd' linker instead of the default linker.
1
1 '-fuse-ld=gold'
1 Use the 'gold' linker instead of the default linker.
1
1 '-fuse-ld=lld'
1 Use the LLVM 'lld' linker instead of the default linker.
1
1 '-lLIBRARY'
1 '-l LIBRARY'
1 Search the library named LIBRARY when linking. (The second
1 alternative with the library as a separate argument is only for
1 POSIX compliance and is not recommended.)
1
1 It makes a difference where in the command you write this option;
1 the linker searches and processes libraries and object files in the
1 order they are specified. Thus, 'foo.o -lz bar.o' searches library
1 'z' after file 'foo.o' but before 'bar.o'. If 'bar.o' refers to
1 functions in 'z', those functions may not be loaded.
1
1 The linker searches a standard list of directories for the library,
1 which is actually a file named 'libLIBRARY.a'. The linker then
1 uses this file as if it had been specified precisely by name.
1
1 The directories searched include several standard system
1 directories plus any that you specify with '-L'.
1
1 Normally the files found this way are library files--archive files
1 whose members are object files. The linker handles an archive file
1 by scanning through it for members which define symbols that have
1 so far been referenced but not defined. But if the file that is
1 found is an ordinary object file, it is linked in the usual
1 fashion. The only difference between using an '-l' option and
1 specifying a file name is that '-l' surrounds LIBRARY with 'lib'
1 and '.a' and searches several directories.
1
1 '-lobjc'
1 You need this special case of the '-l' option in order to link an
1 Objective-C or Objective-C++ program.
1
1 '-nostartfiles'
1 Do not use the standard system startup files when linking. The
1 standard system libraries are used normally, unless '-nostdlib' or
1 '-nodefaultlibs' is used.
1
1 '-nodefaultlibs'
1 Do not use the standard system libraries when linking. Only the
1 libraries you specify are passed to the linker, and options
1 specifying linkage of the system libraries, such as
1 '-static-libgcc' or '-shared-libgcc', are ignored. The standard
1 startup files are used normally, unless '-nostartfiles' is used.
1
1 The compiler may generate calls to 'memcmp', 'memset', 'memcpy' and
1 'memmove'. These entries are usually resolved by entries in libc.
1 These entry points should be supplied through some other mechanism
1 when this option is specified.
1
1 '-nostdlib'
1 Do not use the standard system startup files or libraries when
1 linking. No startup files and only the libraries you specify are
1 passed to the linker, and options specifying linkage of the system
1 libraries, such as '-static-libgcc' or '-shared-libgcc', are
1 ignored.
1
1 The compiler may generate calls to 'memcmp', 'memset', 'memcpy' and
1 'memmove'. These entries are usually resolved by entries in libc.
1 These entry points should be supplied through some other mechanism
1 when this option is specified.
1
1 One of the standard libraries bypassed by '-nostdlib' and
1 '-nodefaultlibs' is 'libgcc.a', a library of internal subroutines
1 which GCC uses to overcome shortcomings of particular machines, or
11 special needs for some languages. (⇒Interfacing to GCC
Output (gccint)Interface, for more discussion of 'libgcc.a'.) In
1 most cases, you need 'libgcc.a' even when you want to avoid other
1 standard libraries. In other words, when you specify '-nostdlib'
1 or '-nodefaultlibs' you should usually specify '-lgcc' as well.
1 This ensures that you have no unresolved references to internal GCC
1 library subroutines. (An example of such an internal subroutine is
11 '__main', used to ensure C++ constructors are called; ⇒
'collect2' (gccint)Collect2.)
1
1 '-pie'
1 Produce a dynamically linked position independent executable on
1 targets that support it. For predictable results, you must also
1 specify the same set of options used for compilation ('-fpie',
1 '-fPIE', or model suboptions) when you specify this linker option.
1
1 '-no-pie'
1 Don't produce a dynamically linked position independent executable.
1
1 '-static-pie'
1 Produce a static position independent executable on targets that
1 support it. A static position independent executable is similar to
1 a static executable, but can be loaded at any address without a
1 dynamic linker. For predictable results, you must also specify the
1 same set of options used for compilation ('-fpie', '-fPIE', or
1 model suboptions) when you specify this linker option.
1
1 '-pthread'
1 Link with the POSIX threads library. This option is supported on
1 GNU/Linux targets, most other Unix derivatives, and also on x86
1 Cygwin and MinGW targets. On some targets this option also sets
1 flags for the preprocessor, so it should be used consistently for
1 both compilation and linking.
1
1 '-rdynamic'
1 Pass the flag '-export-dynamic' to the ELF linker, on targets that
1 support it. This instructs the linker to add all symbols, not only
1 used ones, to the dynamic symbol table. This option is needed for
1 some uses of 'dlopen' or to allow obtaining backtraces from within
1 a program.
1
1 '-s'
1 Remove all symbol table and relocation information from the
1 executable.
1
1 '-static'
1 On systems that support dynamic linking, this overrides '-pie' and
1 prevents linking with the shared libraries. On other systems, this
1 option has no effect.
1
1 '-shared'
1 Produce a shared object which can then be linked with other objects
1 to form an executable. Not all systems support this option. For
1 predictable results, you must also specify the same set of options
1 used for compilation ('-fpic', '-fPIC', or model suboptions) when
1 you specify this linker option.(1)
1
1 '-shared-libgcc'
1 '-static-libgcc'
1 On systems that provide 'libgcc' as a shared library, these options
1 force the use of either the shared or static version, respectively.
1 If no shared version of 'libgcc' was built when the compiler was
1 configured, these options have no effect.
1
1 There are several situations in which an application should use the
1 shared 'libgcc' instead of the static version. The most common of
1 these is when the application wishes to throw and catch exceptions
1 across different shared libraries. In that case, each of the
1 libraries as well as the application itself should use the shared
1 'libgcc'.
1
1 Therefore, the G++ driver automatically adds '-shared-libgcc'
1 whenever you build a shared library or a main executable, because
1 C++ programs typically use exceptions, so this is the right thing
1 to do.
1
1 If, instead, you use the GCC driver to create shared libraries, you
1 may find that they are not always linked with the shared 'libgcc'.
1 If GCC finds, at its configuration time, that you have a non-GNU
1 linker or a GNU linker that does not support option
1 '--eh-frame-hdr', it links the shared version of 'libgcc' into
1 shared libraries by default. Otherwise, it takes advantage of the
1 linker and optimizes away the linking with the shared version of
1 'libgcc', linking with the static version of libgcc by default.
1 This allows exceptions to propagate through such shared libraries,
1 without incurring relocation costs at library load time.
1
1 However, if a library or main executable is supposed to throw or
1 catch exceptions, you must link it using the G++ driver, or using
1 the option '-shared-libgcc', such that it is linked with the shared
1 'libgcc'.
1
1 '-static-libasan'
1 When the '-fsanitize=address' option is used to link a program, the
1 GCC driver automatically links against 'libasan'. If 'libasan' is
1 available as a shared library, and the '-static' option is not
1 used, then this links against the shared version of 'libasan'. The
1 '-static-libasan' option directs the GCC driver to link 'libasan'
1 statically, without necessarily linking other libraries statically.
1
1 '-static-libtsan'
1 When the '-fsanitize=thread' option is used to link a program, the
1 GCC driver automatically links against 'libtsan'. If 'libtsan' is
1 available as a shared library, and the '-static' option is not
1 used, then this links against the shared version of 'libtsan'. The
1 '-static-libtsan' option directs the GCC driver to link 'libtsan'
1 statically, without necessarily linking other libraries statically.
1
1 '-static-liblsan'
1 When the '-fsanitize=leak' option is used to link a program, the
1 GCC driver automatically links against 'liblsan'. If 'liblsan' is
1 available as a shared library, and the '-static' option is not
1 used, then this links against the shared version of 'liblsan'. The
1 '-static-liblsan' option directs the GCC driver to link 'liblsan'
1 statically, without necessarily linking other libraries statically.
1
1 '-static-libubsan'
1 When the '-fsanitize=undefined' option is used to link a program,
1 the GCC driver automatically links against 'libubsan'. If
1 'libubsan' is available as a shared library, and the '-static'
1 option is not used, then this links against the shared version of
1 'libubsan'. The '-static-libubsan' option directs the GCC driver
1 to link 'libubsan' statically, without necessarily linking other
1 libraries statically.
1
1 '-static-libmpx'
1 When the '-fcheck-pointer bounds' and '-mmpx' options are used to
1 link a program, the GCC driver automatically links against
1 'libmpx'. If 'libmpx' is available as a shared library, and the
1 '-static' option is not used, then this links against the shared
1 version of 'libmpx'. The '-static-libmpx' option directs the GCC
1 driver to link 'libmpx' statically, without necessarily linking
1 other libraries statically.
1
1 '-static-libmpxwrappers'
1 When the '-fcheck-pointer bounds' and '-mmpx' options are used to
1 link a program without also using '-fno-chkp-use-wrappers', the GCC
1 driver automatically links against 'libmpxwrappers'. If
1 'libmpxwrappers' is available as a shared library, and the
1 '-static' option is not used, then this links against the shared
1 version of 'libmpxwrappers'. The '-static-libmpxwrappers' option
1 directs the GCC driver to link 'libmpxwrappers' statically, without
1 necessarily linking other libraries statically.
1
1 '-static-libstdc++'
1 When the 'g++' program is used to link a C++ program, it normally
1 automatically links against 'libstdc++'. If 'libstdc++' is
1 available as a shared library, and the '-static' option is not
1 used, then this links against the shared version of 'libstdc++'.
1 That is normally fine. However, it is sometimes useful to freeze
1 the version of 'libstdc++' used by the program without going all
1 the way to a fully static link. The '-static-libstdc++' option
1 directs the 'g++' driver to link 'libstdc++' statically, without
1 necessarily linking other libraries statically.
1
1 '-symbolic'
1 Bind references to global symbols when building a shared object.
1 Warn about any unresolved references (unless overridden by the link
1 editor option '-Xlinker -z -Xlinker defs'). Only a few systems
1 support this option.
1
1 '-T SCRIPT'
1 Use SCRIPT as the linker script. This option is supported by most
1 systems using the GNU linker. On some targets, such as bare-board
1 targets without an operating system, the '-T' option may be
1 required when linking to avoid references to undefined symbols.
1
1 '-Xlinker OPTION'
1 Pass OPTION as an option to the linker. You can use this to supply
1 system-specific linker options that GCC does not recognize.
1
1 If you want to pass an option that takes a separate argument, you
1 must use '-Xlinker' twice, once for the option and once for the
1 argument. For example, to pass '-assert definitions', you must
1 write '-Xlinker -assert -Xlinker definitions'. It does not work to
1 write '-Xlinker "-assert definitions"', because this passes the
1 entire string as a single argument, which is not what the linker
1 expects.
1
1 When using the GNU linker, it is usually more convenient to pass
1 arguments to linker options using the 'OPTION=VALUE' syntax than as
1 separate arguments. For example, you can specify '-Xlinker
1 -Map=output.map' rather than '-Xlinker -Map -Xlinker output.map'.
1 Other linkers may not support this syntax for command-line options.
1
1 '-Wl,OPTION'
1 Pass OPTION as an option to the linker. If OPTION contains commas,
1 it is split into multiple options at the commas. You can use this
1 syntax to pass an argument to the option. For example,
1 '-Wl,-Map,output.map' passes '-Map output.map' to the linker. When
1 using the GNU linker, you can also get the same effect with
1 '-Wl,-Map=output.map'.
1
1 '-u SYMBOL'
1 Pretend the symbol SYMBOL is undefined, to force linking of library
1 modules to define it. You can use '-u' multiple times with
1 different symbols to force loading of additional library modules.
1
1 '-z KEYWORD'
1 '-z' is passed directly on to the linker along with the keyword
1 KEYWORD. See the section in the documentation of your linker for
1 permitted values and their meanings.
1
1 ---------- Footnotes ----------
1
1 (1) On some systems, 'gcc -shared' needs to build supplementary stub
1 code for constructors to work. On multi-libbed systems, 'gcc -shared'
1 must select the correct support libraries to link against. Failing to
1 supply the correct flags may lead to subtle defects. Supplying them in
1 cases where they are not necessary is innocuous.
1