Next:Options for Directory Search, Previous:Passing Options to the Assembler, Up:GCC Command Options [Contents][Index]
These options come into play when the compiler links object files intoan executable output file. They are meaningless if the compiler isnot doing a link step.
object-file-name ¶A file name that does not end in a special recognized suffix isconsidered to name an object file or library. (Object files aredistinguished from libraries by the linker according to the filecontents.) If linking is done, these object files are used as inputto the linker.
-c ¶-S-EIf any of these options is used, then the linker is not run, andobject file names should not be used as arguments. SeeOptions Controlling the Kind of Output.
-flink-libatomic ¶Enable linking of libatomic if it’s supported by target, and is enabled bydefault. The negative form-fno-link-libatomic can be used toexplicitly disable linking of libatomic.
-flinker-output=type ¶This option controls code generation of the link-time optimizer. Bydefault the linker output is automatically determined by the linkerplugin. For debugging the compiler and if incremental linking with anon-LTO object file is desired, it may be useful to control the typemanually.
Iftype is ‘exec’, code generation produces a staticbinary. In this case-fpic and-fpie are bothdisabled.
Iftype is ‘dyn’, code generation produces a sharedlibrary. In this case-fpic or-fPIC is preserved,but not enabled automatically. This allows to build shared librarieswithout position-independent code on architectures where this ispossible, i.e. on x86.
Iftype is ‘pie’, code generation produces an-fpieexecutable. This results in similar optimizations as ‘exec’except that-fpie is not disabled if specified at compilationtime.
Iftype is ‘rel’, the compiler assumes that incremental linking isdone. The sections containing intermediate code for link-time optimization aremerged, pre-optimized, and output to the resulting object file. In addition, if-ffat-lto-objects is specified, binary code is produced for futurenon-LTO linking. The object file produced by incremental linking is smallerthan a static library produced from the same object files. At link time theresult of incremental linking also loads faster than a staticlibrary assuming that the majority of objects in the library are used.
Finally ‘nolto-rel’ configures the compiler for incremental linking wherecode generation is forced, a final binary is produced, and the intermediatecode for later link-time optimization is stripped. When multiple object filesare linked together the resulting code is better optimized than withlink-time optimizations disabled (for example, cross-module inlininghappens), but most of the benefits of whole-program optimizations are lost.
During the incremental link (by-r) the linker plugin defaults torel. GNU Binutils 2.44 or later is needed to incrementally linkLTO objects and non-LTO objects into a single mixed object file. If anyof the object files in an incremental link cannot be used for link-timeoptimization, the linker plugin issues a warning and uses ‘nolto-rel’.To maintain whole-program optimization, link such objects into a staticlibrary instead.
-fuse-ld=bfd ¶Use thebfd linker instead of the default linker.
-fuse-ld=gold ¶Use thegold linker instead of the default linker.
-fuse-ld=lld ¶Use the LLVMlld linker instead of the default linker.
-fuse-ld=mold ¶Use the Modern Linker (mold) instead of the default linker.
-llibrary ¶-llibrarySearch the library namedlibrary when linking. (The secondalternative with the library as a separate argument is only forPOSIX compliance and is not recommended.)
The-l option is passed directly to the linker by GCC. Referto your linker documentation for exact details. The generaldescription below applies to the GNU linker.
The linker searches a standard list of directories for the library.The directories searched include several standard system directoriesplus any that you specify with-L.
Static libraries are archives of object files, and have file nameslikeliblibrary.a. Some targets also support sharedlibraries, which typically have names likeliblibrary.so.If both static and shared libraries are found, the linker givespreference to linking with the shared library unless the-static option is used.
It makes a difference where in the command you write this option; thelinker searches and processes libraries and object files in the order theyare specified. Thus, ‘foo.o -lz bar.o’ searches library ‘z’after filefoo.o but beforebar.o. Ifbar.o refersto functions in ‘z’, those functions may not be loaded.
-lobjc ¶You need this special case of the-l option in order tolink 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 optionsspecifying linkage of the system libraries, such as-static-libgccor-shared-libgcc, are ignored.The standard startup files are used normally, unless-nostartfilesis used.
The compiler may generate calls tomemcmp,memset,memcpy andmemmove.These entries are usually resolved by entries inlibc. These entry points should be supplied through some othermechanism when this option is specified.
-nolibc ¶Do not use the C library or system libraries tightly coupled with it whenlinking. Still link with the startup files,libgcc or toolchainprovided language support libraries such aslibgnat,libgfortranorlibstdc++ unless options preventing their inclusion are used aswell. This typically removes-lc from the link command line, as wellas system libraries that normally go with it and become meaningless whenabsence of a C library is assumed, for example-lpthread or-lm in some configurations. This is intended for bare-boardtargets when there is indeed no C library available.
-nostdlib ¶--no-standard-librariesDo not use the standard system startup files or libraries when linking.No startup files and only the libraries you specify are passed tothe linker, and options specifying linkage of the system libraries, such as-static-libgcc or-shared-libgcc, are ignored.
The compiler may generate calls tomemcmp,memset,memcpy andmemmove.These entries are usually resolved by entries inlibc. These entry points should be supplied through some othermechanism when this option is specified.
One of the standard libraries bypassed by-nostdlib and-nodefaultlibs islibgcc.a, a library of internal subroutineswhich GCC uses to overcome shortcomings of particular machines, or specialneeds for some languages.(SeeInterfacing to GCC Output inGNU CompilerCollection (GCC) Internals,for more discussion oflibgcc.a.)In most cases, you needlibgcc.a even when you want to avoidother standard libraries. In other words, when you specify-nostdlibor-nodefaultlibs you should usually specify-lgcc as well.This ensures that you have no unresolved references to internal GCClibrary subroutines.(An example of such an internal subroutine is__main, used to ensure C++constructors are called; seecollect2 inGNU Compiler Collection (GCC) Internals.)
-nostdlib++ ¶Do not implicitly link with standard C++ libraries.
-eentry ¶--entry=entry--entryentrySpecify that the program entry point isentry. The argument isinterpreted by the linker; the GNU linker accepts either a symbol nameor an address.
-pie ¶--pieProduce a dynamically linked position independent executable on targetsthat support it. For predictable results, you must also specify the sameset 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 ¶--static-pieProduce a static position independent executable on targets that supportit. A static position independent executable is similar to a staticexecutable, but can be loaded at any address without a dynamic linker.For predictable results, you must also specify the same set of optionsused for compilation (-fpie,-fPIE, or modelsuboptions) when you specify this linker option.
-pthread ¶Link with the POSIX threads library. This option is supported onGNU/Linux targets, most other Unix derivatives, and also onx86 Cygwin and MinGW targets. On some targets this option also setsflags for the preprocessor, so it should be used consistently for bothcompilation and linking.
-r ¶Produce a relocatable object as output. This is also known as partiallinking.
-rdynamic ¶Pass the flag-export-dynamic to the ELF linker, on targetsthat support it. This instructs the linker to add all symbols, notonly used ones, to the dynamic symbol table. This option is neededfor some uses ofdlopen or to allow obtaining backtracesfrom within a program.
-s ¶Remove all symbol table and relocation information from the executable.
-static ¶--staticOn systems that support dynamic linking, this overrides-pieand prevents linking with the shared libraries. On other systems, thisoption has no effect.
-shared ¶--sharedProduce a shared object which can then be linked with other objects toform an executable. Not all systems support this option. For predictableresults, you must also specify the same set of options used for compilation(-fpic,-fPIC, or model suboptions) whenyou specify this linker option.1
-shared-libgcc ¶-static-libgccOn systems that providelibgcc as a shared library, these optionsforce the use of either the shared or static version, respectively.If no shared version oflibgcc was built when the compiler wasconfigured, these options have no effect.
There are several situations in which an application should use thesharedlibgcc instead of the static version. The most commonof these is when the application wishes to throw and catch exceptionsacross different shared libraries. In that case, each of the librariesas well as the application itself should use the sharedlibgcc.
Therefore, the G++ driver automatically adds-shared-libgccwhenever 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 mayfind that they are not always linked with the sharedlibgcc.If GCC finds, at its configuration time, that you have a non-GNU linkeror a GNU linker that does not support option--eh-frame-hdr,it links the shared version oflibgcc into shared librariesby default. Otherwise, it takes advantage of the linker and optimizesaway the linking with the shared version oflibgcc, linking withthe static version of libgcc by default. This allows exceptions topropagate through such shared libraries, without incurring relocationcosts at library load time.
However, if a library or main executable is supposed to throw or catchexceptions, you must link it using the G++ driver, or using the option-shared-libgcc, such that it is linked with the sharedlibgcc.
-static-libasan ¶When the-fsanitize=address option is used to link a program,the GCC driver automatically links againstlibasan. Iflibasan is available as a shared library, and the-staticoption is not used, then this links against the shared version oflibasan. The-static-libasan option directs the GCCdriver to linklibasan statically, without necessarily linkingother libraries statically.
-static-libtsan ¶When the-fsanitize=thread option is used to link a program,the GCC driver automatically links againstlibtsan. Iflibtsan is available as a shared library, and the-staticoption is not used, then this links against the shared version oflibtsan. The-static-libtsan option directs the GCCdriver to linklibtsan statically, without necessarily linkingother libraries statically.
-static-liblsan ¶When the-fsanitize=leak option is used to link a program,the GCC driver automatically links againstliblsan. Ifliblsan is available as a shared library, and the-staticoption is not used, then this links against the shared version ofliblsan. The-static-liblsan option directs the GCCdriver to linkliblsan statically, without necessarily linkingother libraries statically.
-static-libubsan ¶When the-fsanitize=undefined option is used to link a program,the GCC driver automatically links againstlibubsan. Iflibubsan is available as a shared library, and the-staticoption is not used, then this links against the shared version oflibubsan. The-static-libubsan option directs the GCCdriver to linklibubsan statically, without necessarily linkingother libraries statically.
-static-libstdc++ ¶When theg++ program is used to link a C++ program, itnormally automatically links againstlibstdc++. Iflibstdc++ is available as a shared library, and the-static option is not used, then this links against theshared version oflibstdc++. That is normally fine. However, itis sometimes useful to freeze the version oflibstdc++ used bythe program without going all the way to a fully static link. The-static-libstdc++ option directs theg++ driver tolinklibstdc++ statically, without necessarily linking otherlibraries statically.
-symbolic ¶--symbolicBind references to global symbols when building a shared object. Warnabout any unresolved references (unless overridden by the link editoroption-Xlinker -z -Xlinker defs). Only a few systems supportthis option.
-Tscript ¶Usescript as the linker script. This option is supported by mostsystems using the GNU linker. On some targets, such as bare-boardtargets without an operating system, the-T option may be requiredwhen linking to avoid references to undefined symbols.
-Xlinkeroption ¶Passoption as an option to the linker. You can use this tosupply 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 entirestring as a single argument, which is not what the linker expects.
When using the GNU linker, it is usually more convenient to passarguments to linker options using theoption=valuesyntax than as separate arguments. For example, you can specify-Xlinker -Map=output.map rather than-Xlinker -Map -Xlinker output.map. Other linkers may not supportthis syntax for command-line options.
-Wl,option ¶--for-linker=option--for-linkeroptionPassoption as an option to the linker. Ifoption containscommas, it is split into multiple options at the commas. You can use thissyntax to pass an argument to the option.For example,-Wl,-Map,output.map passes-Map output.map to thelinker. When using the GNU linker, you can also get the same effect with-Wl,-Map=output.map.
-usymbol ¶--force-link=symbol--force-linksymbolPretend the symbolsymbol is undefined, to force linking oflibrary modules to define it. You can use-u multiple times withdifferent symbols to force loading of additional library modules.
-Tbss=addr ¶-Tdata=addr-Ttext=addr-N-n-t-Z-zkeywordThese options are passed through to the linker without interpretation by GCC.Refer to your linker documentation for the meanings of these options.
On some systems, ‘gcc -shared’needs to build supplementary stub code for constructors to work. Onmulti-libbed systems, ‘gcc -shared’ must select the correct supportlibraries to link against. Failing to supply the correct flags may leadto subtle defects. Supplying them in cases where they are not necessaryis innocuous.-shared suppresses the addition of startup codeto alter the floating-point environment as done with-ffast-math,-Ofast or-funsafe-math-optimizations on some targets.
Next:Options for Directory Search, Previous:Passing Options to the Assembler, Up:GCC Command Options [Contents][Index]