Compatibility Or Ignored Options

-EL

Link little endian objects.

-Qy

This option is ignored for SVR4 compatibility

--add-needed

Deprecated

--copy-dt-needed-entries

Add the dynamic libraries mentioned to DT_NEEDED

--ignore-unknown-opts

Disable warnings of unimplemented options

--nmagic

Turn off page alignment of sections, and disable linking against shared libraries

--no-add-needed

Deprecated

--no-allow-shlib-undefined

Do not allow undefined symbols from dynamic library when creating executables

--no-copy-dt-needed-entries

Turn off the effect of the –copy-dt-needed-entries

--plugin <pluginfile>

Specify a plugin file

--plugin-opt <plugin-opt>

Specify plugin options

-thin-archive-rule-matching-compatibility, --thin-archive-rule-matching-compatibility

Provides rule-matching compatibility when fat archives are converted to thin archives

DIAGNOSITC OPTIONS

-W<warn-type>

Print warnings which are OFF by default

  • -Wall : print all warnings

  • -W[no]linker-script : display warnings detected while parsing linker scripts

  • -W[no]attribute-mix : display a warning if object files of RISC-V with different attributes are being linked

  • -W[no-]archive-file : display warnings detected while reading archive files

  • -W[no-]linker-script-memory : display warnings detected while processing linker script memory command

  • -W[no-]bad-dot-assignments : display warnings for bad dot assignments

  • -W[no-]error : treat warnings as errors

  • -W[no-]whole-archive : display a warning when whole-archive is enabled for any archive file

  • -W[no-]osabi : display a warning when linking objects with different values for OS/ABI

  • -W[no-]version-script : display warnings detected while processing version scripts

--color <never/always/auto>

Enable color output for diagnostics

--cref

Print the references for a symbol or section

-t

Print all files processed by the linker

--display-hotness <value>

Display hotness information for optimization remarks

--emit-timing-stats <filename>

Emit time statistics of various linker operations to the specified file

--emit-timing-stats-in-output

Insert link-time stats in section .note.qc.timing

--error-limit <max-error-number>

Maximum number of errors to emit before stopping (0 = no limit)

--error-style <style>

Specify an error style, LLVM/GNU

--fatal-internal-errors

Enable fatal internal errors

--fatal-warnings

Enable fatal warnings

--gc-cref <symbol/section>

Print the references for a symbol or section when garbage collection is enabled

--no-fatal-internal-errors

Disable fatal internal errors

--no-fatal-warnings

Disable fatal warnings

--no-warn-mismatch

Do not Warn on incompatible files passed to the linker.

--opt-record-file

Create diagnostic yaml file

--print-timing-stats

Print time statistics of various linker operations to console

--progress-bar

Show Progress Bar

--summary

Display linker run summary at the end

--time-region <region>

Emit time statistics for specified region of linker operation

--trace <trace-type>

Allow tracing of

  • –trace=linker-script : trace linker script

  • –trace=files : trace input files

  • –trace=reloc=<pattern> : trace relocations

  • –trace=symbol=<symbol-name> : trace symbol

  • –trace=all-symbols : trace all symbols

  • –trace=LTO : trace LTO

  • –trace=garbage-collection : trace linker garbage collection

  • –trace=plugin : trace plugin

  • –trace=threads : trace threads

  • –trace=assignments : trace symbol assignments

  • –trace=command-line : trace header info

  • –trace=live-edges : trace reachable sections when garbage collection is enabled

  • –trace=merge-strings : trace linker string optimization

  • –trace=trampolines : trace trampolines

  • –trace=untar : trace tar extraction entries

  • –trace=wrap-symbols : trace symbol wrap options

  • –trace=symdef : trace symbol resolution from symdef files

  • –trace=dynamic-linking : trace dynamic linking

  • –trace=symbol-versioning : trace symbol versioning

--trace-linker-script

Trace stages of linker script processing

--trace-lto

Trace stages of lto

--trace-merge-strings <option>

Emit diagnostics describing how strings were merged. Options: all(default), allocatable_sections, <output section (regex)>

--trace-reloc <relocation>

trace a particular relocation

--trace-section <section_name>

Show metadata about a particular section

-y <symbol>

Trace a particular symbol

--verbose

Enable verbose output

--verbose=<verbose-level>

Enable verbose output

--verify-options <option>

Verify certain internal linker computations - currently supports reloc

--warn-common

Warn on common symbols

--warn-limit <maxwarnings>

Maximum number of warnings to emit (0 = no limit)

--warn-mismatch

Warn on incompatible files passed to the linker.

DYNAMIC LIBRARY OPTIONS

--Bgroup

Enable runtime linker to handle lookups in this object and its dependencies to be performed only inside this group

--Bsymbolic

Bind references to global symbols to the definition within the shared library

--Bsymbolic-functions

Bind references to global functions to the definition within the shared library

-g

Enable debug output when building shared libraries or executables

-fPIC

Enable PIC mode

--hash-size <size>

Specify a hash size when creating the hash sections for the dynamic loader

--hash-style <hashstyle>

Specify a hash style when creating the hash sections for the dynamic loader

--no-warn-shared-textrel

Don’t Warn if the linker adds a DT_TEXTREL

--soname <name>

Set the internal DT_SONAME field to the specified name

--warn-shared-textrel

Warn if the linker adds a DT_TEXTREL

DYNAMIC LIBRARY/EXECUTABLE OPTIONS

--dynamic-linker <path>

Set the path to the dynamic linker

--export-dynamic

Add all symbols to the dynamic symbol table when creating executables

--export-dynamic-symbol <symbol>

Export specified symbol to dynamic symbol table

--force-dynamic

Build executable as a force dynamic executable

--no-dynamic-linker

The program does not need a dynamic linker when creating static PIE executables

--no-export-dynamic
--rpath <path>

Add a path to the runtime library search path

Specifies the path to search

Extended Options

--about

Emit detailed information about the linker

--align-segments

Align segments to page boundaries

--allow-bss-conversion

Don’t produce an error when mixing NOBITS, and PROGBITS sections in the same segment

--copy-farcalls-from-file <filename>

Copy far calls instead of using trampolines

-z <extended-opts>

Extended Options or Non standard options.

Available options are:

  • -z=combreloc : Combines multiple reloc sections and sorts them to make dynamic symbol lookup caching

  • -z=now : Enables immediate binding

  • -z=nocopyreloc : Disables Copy Relocation

  • -z=text : Do not permit relocations in read-only segments (default)

  • -z=notext : Allow relocations in read-only segments

  • -z=separate-code : Create separate code segment

  • -z=no-separate-code : Do not create separate code segment

  • -z=separate-loadable-segments : Create separate loadable segments

--disable-linker-version

Disable the LINKER_VERSION linker script directive (default)

--disable-new-dtags

Disable new dynamic tags

--dump-mapping-file <outputfilename>

Dump mapping file to output file

--dump-response-file <outputfilename>

Dump response file to output file

--emit-relocs-llvm

Emit relocations sections

--enable-linker-version

Enable the LINKER_VERSION linker script directive

--enable-new-dtags

Enable new dynamic tags

--mapping-file <INI-file>

Reproduce link using a mapping file

--no-align-segments

Don’t align segments to page boundaries

--no-emit-relocs

Don’t emit relocations in the output file, applicable to –emit-relocs-llvm option too

--no-record-command-line

Do not record the linker command line in the comment section

--no-reuse-trampolines-file <filename>

Don’t reuse trampolines for symbols specified in file

--no-verify

Don’t verify link output

--record-command-line

Record the linker command line in the comment section

--reproduce <tarfilename>|default

Write a tar file containing input files and command line options to inspect and re-link

--reproduce-compressed <tarfilename>

Write compressed tar file in zlib format containing input files and command line options to inspect and re-link.

--reproduce-on-fail <tarfilename>|default

Write reproduce tar file when link fails containing input files and command line options to inspect and re-link.

--rosegment

Put read-only non-executable sections in their own segment

--script-options <matchtype>

Specify a match type, match-gnu/match-llvm

--use-old-rule-matching

Use the original (pre-optimization) linker script rule-matching algorithm

--use-old-style-trampoline-name

Use old style of naming trampolines

GENERAL OPTIONS

--build-id

Request creation of “.note.gnu.build-id” ELF note section

--build-id=fast/md5/sha1/tree/uuid/0x<hexstring>/none

Request creation of “.note.gnu.build-id” ELF note section

--no-warn-rwx-segments

Silence warnings for segments with RWX permissions

-o <outputfile>

Path to file to write output

--repository-version

Print the Linker Repository version

--sysroot <sysroot-path>

Set the system root

INPUT(file, file, ...)
GROUP(file, file, ...)

The files specified using the INPUT and GROUP command are searched inside the sysroot when:

  • The file begins with the / character, and

  • The script containing the INPUT/GROUP command is located within the sysroot directory.

Additionally, paths in INPUT/GROUP commands or on the command line can explicitly force sysroot expansion by using the = or $SYSROOT prefix:

  • =/path/to/file expands to <sysroot>/path/to/file

  • $SYSROOT/path/to/file expands to <sysroot>/path/to/file

This works for both linker script commands and command-line input files. If no sysroot is configured, the prefix is stripped and the remaining path is used.

-L <search_directory>

When <search_directory> is prefixed with =, then = is expanded to the sysroot.

--version

Print the Linker version

--warn-rwx-segments

Warn if the linker creates a segment with RWX permissions (default)

Help!

--help

Print option help

--help-hidden

Print hidden option help

Input Format

-b <input-format>
Specify input format for inputs following this option.

Supported values: binary,default

--remap-inputs <pattern=filename>

Rules are evaluated in command-line order; the first matching rule wins. The pattern supports wildcard matching.

Example:

--remap-inputs=foo.o=bar.o
--remap-inputs=*foo.o=build/alt/bar.o

Remapping is applied before path search/open, including linker-script INPUT(...), GROUP(...), and INCLUDE processing.

How to tell remapping is active:

--verbose prints: Remapping input file <old> to <new>.
Text map output (-MapStyle txt) annotates remapped entries with
# remapped from <original-name>.
--remap-inputs-file <file>

Read remap rules from <file>.

Each non-empty line in the file is one rule in either format:

pattern=replacement
pattern replacement

Lines beginning with # and blank lines are ignored. Inline # comments are also supported.

Rules from this file are appended to the same ordered remap list used by --remap-inputs.

OUTPUT KIND

--Bdynamic

Link against dynamic library

--dynamic

Create dynamic executable (default)

--no-pie

Do not create a PIE executable

--pie

Create PIE executable

-r

Create relocatable object file

--shared

Create dynamic library

--static

Create static executable

LLVM and Target Options

-m

Select target emulation

-mabi <mabi>

Target ABI

-march <march>

Target architecture

-mcpu <mcpu>

Target CPU

-mllvm <option>

Options to pass to LLVM

-mtriple <triple>

Target triple to link for

LTO Options

--disable-verify, -disable-verify

Do not run the verifier during the optimization pipeline

--dwodir <dir>

Directory to save .dwo files when split DWARF is used in LTO

--exclude-lto-filelist <list_of_files>

Specify a list of files that are to be disregarded while using embedded bitcode section for LTO. This has no effect if -flto switch is not used.

--fat-lto-objects

Use .llvm.lto section in fat LTO objects

--flto

Enable LTO if a Bitcode file is present.

--flto-options <option>

Specify various options with LTO

--flto-use-as

Use the standalone assembler instead of the integrated assembler for LTO

--include-lto-filelist <list_of_files>

Specify a list of files with embedded bitcode sections that are to be used for LTO. This has no effect if -flto switch is used

--lto-O<opt-level>

Optimization level for LTO

--lto-cs-profile-file=<value>

Context sensitive profile file path

--lto-cs-profile-generate

Perform context sensitive PGO instrumentation

--lto-debug-pass-manager

Debug new pass manager

--lto-emit-asm

Emit assembly code

--lto-emit-llvm

Emit LLVM-IR bitcode

--lto-obj-path=<prefix>

Specify file path used as a prefix for output LTO object files. Files created with this prefix will not be deleted after LTO finishes.

--lto-partitions=<number>

Number of LTO codegen partitions

--lto-sample-profile=<file>

Sample PGO profile file to be loaded for LTO

--no-fat-lto-objects

Ignore .llvm.lto section in fat LTO objects

--opt-remarks-filename <value>

YAML output file for optimization remarks

--opt-remarks-format <value>

The format used for serializing remarks (default: YAML)

--opt-remarks-hotness-threshold <value>
--opt-remarks-passes <value>

Regex for the passes that need to be serialized to the output file

--opt-remarks-with-hotness

Include hotness information in the optimization remarks file

--plugin-opt=-<value>, -plugin-opt=-<value>

Specify an LLVM option for compatibility with LLVMgold.so

--plugin-opt=stats-file=<value>, -plugin-opt=stats-file=<value>

Filename to write LTO statistics to

--save-temps

Save the temporary files produced by LTO

--save-temps=<dir>

Save the temporary files produced by LTO in the directory

--thinlto-jobs=<number>

Number of ThinLTO jobs. Default to –threads=

EXECUTABLE OPTIONS

-L

Path to search for libraries or linker scripts

-Y <path>

Add path to the default library search path

--emit-relocs

Make Emit relocs behave just like GNU.

-e <symbolname>

Name of entry point symbol

--fini <symbol>

Specify a finalizer function

--image-base <address>
--init <symbol>

Specify an initializer function

-l

Root name of library to use

--library-path <path>

Path to search for libraries or linker scripts

--library=<namespec>

library to use

--no-omagic

This option negates most of the effects of the -N option. Disable linking with shared libraries

--no-whole-archive

Restores the default behavior of loading archive members

--noinhibit-exec

Retain the executable output file whenever it is still usable

--nostdlib

Disable default search path for libraries

--omagic

Set the text and data sections to be readable and writable. Also, do not page-align the data segment, and disable linking against shared libraries.

--whole-archive

Force load of all members in a static library

Map Options

--Map <filename>

Dump the output layout to the map file

--MapDetail <option>

Detail information in the map file

--MapStyle <fileformat>

Dump the output layout to the map file in YAML/Text/Binary Form

-M

Emit the map file

--trampoline-map <filename>

Dump Trampoline Information in YAML format

--color-map

Color the map file

Misc Features

--archive-member-report <filename>

Emit JSON report for archive members pulled in by symbols

--allow-incompatible-section-mix

Allow incompatible section mix

OPTIMIZATION OPTIONS

--eh-frame-hdr

Create EH Frame Header section for faster exception handling

--gc-sections

Enable garbage collection

--no-gc-sections

Disable garbage collection

--no-merge-strings

Disable String Merging

--no-trampolines

Disable Trampolines

--print-gc-sections

Print sections that are garbage collected

--sframe-hdr

Process and emit .sframe sections for stack unwinding

Features From other Linkers

-R <filename>

Read symbol names and addresses from filename

--symdef

Output SymDef file to console

--symdef-file <filename>

Emit SymDef file

--symdef-style <style>

Determine how to handle symbol resolution for symbols from symdef file, Options available are provide

Plugin Options

--plugin-activity-file <filename>

Emit plugin activity JSON files

--no-default-plugins

Allow no plugins to be implicitly loaded

--plugin-config <config-file>

Specify a plugin configuration

SYMBOL RESOLUTION OPTIONS

--allow-multiple-definition

Allow multiple definitions

--allow-shlib-undefined

Allow undefined symbols from dynamic library when creating executables

--as-needed

This option affects ELF DT_NEEDED tags for dynamic libraries mentioned on the command line

--defsym symbol=<expression>

Create a global symbol in the output file containing the absolute address given by expression

--end-group

End a group

--end-lib

End a library

--end-lib-thin

End a thin library

--no-as-needed

This option restores the default behavior of adding DT_NEEDED entries

--no-undefined

Report unresolved symbol references from regular object files

--pop-state

Restore previously saved input handling flags

--push-state

Save current input handling flags (as-needed, whole-archive, etc)

--start-group

Start a group

--start-lib

Start a library

--start-lib-thin

Start a thin library

-u

Force symbol to be entered in the output file as an undefined symbol

--use-shlib-undefines

Resolve undefined symbols from dynamic libraries

--warn-once

Warn only once for every undefined reference

SCRIPT OPTIONS

-T <linkerscriptfile>

Use the given linker script in place of the default script.

--Tbss <address>

Specify an address for the .bss section

--Tdata <address>

Specify an address for the .data section

--Ttext <address>

Specify an address for the .text section

--Ttext-segment <address>

Specify an address for the .text-segment segment

--default-script <pluginfile>

Use the linker script as the default linker script.

--no-check-sections

Do not check section addresses for overlaps

--dynamic-list <list-of-symbols>

Specify a list of symbols if present will be exported

--check-sections

Check section addresses for overlaps(default)

--exclude-libs <libs>

Specifies a list of archive libraries from which symbols should not be automatically exported

--extern-list <list-of-symbols>

Specify a list of symbols that exists as external dependencies

--global-merge-non-alloc-strings

merge non-alloc strings across output sections

--map-section <section>

Specify a input section that maps to a output section

--orphan-handling <mode>

Specify how to handle orphan sections. Options available are place, error, warn

--print-memory-usage

Print memory usage when MEMORY linker script directive is used

--section-start <address>

Specify a virtual output section address for a specified section

--sort-section <sort_section>
--unique-output-sections

Place each input section in a unique output section

--unresolved-symbols <option>

Determine how to handle unresolved symbols, Options available are ignore-all, report-all(Default), ignore-in-object-files, ignore-in-shared-libs

--version-script <linkersciptfile>

Use the linker script as a version script.

SYMBOL OPTIONS

-d

Assign space to common symbols

--demangle

Demangle C++ symbols

--demangle-style <value>

Specify whether the linker should demangle symbols when emitting errors or emitting Map files

--discard-all

Discard all symbols

--discard-locals

Discard all local symbols

--no-demangle

Don’t demangle C++ symbols

--portable <symbol>

Specify symbol to be portable wrapped to

--sort-common

sort common symbols by alignment

--sort-common=<ascending|descending>

Sort common symbols by order of alignment

--strip-all

Omit all symbol information from output

--strip-debug

Omit all debug information from output

--wrap <symbol>

Specify symbol to be wrapped to