Compatibility Or Ignored Options

-EL

Link little endian objects.

-Qy

This option is ignored for SVR4 compatibility

--Ttext-segment <address>

Specify an address for the .text-segment segment

--add-needed

Deprecated

--allow-shlib-undefined

Allow undefined symbols from dynamic library when creating executables

--copy-dt-needed-entries

Add the dynamic libraries mentioned to DT_NEEDED

-g

Enable debug output when building shared libraries or executables

--hash-size <size>

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

--ignore-unknown-opts

Disable warnings of unimplemented options

--map-section <section>

Specify a input section that maps to a output section

--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

Specifies the path to search

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

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

--use-shlib-undefines

Resolve undefined symbols from dynamic libraries

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=plugin=<plugin-name> : trace a single 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

-fPIC

Enable PIC mode

--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

--default-symver

Create a default symbol version node, that is used for unversioned exported symbols

--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

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.

-v

Print the Linker version and continue processing

--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.

Rules are evaluated in command-line order; the first matching rule wins. The pattern supports wildcard matching. For example, remap.txt can contain:

foo.o=bar.o
*foo.o=build/alt/bar.o

When used with --reproduce, the remap file is copied into the reproduce archive and the generated response.txt refers to the captured replacement paths. This allows the extracted archive to be replayed without access to the original remap file or the original input paths.

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=<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

--emit-symbol-resolution-report <filename>

Emit JSON symbol resolution report

--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

--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

--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

--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

--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