17. Command-line options

Here’s the list of command-line options accepted by the ELD:

17.1. Common options for all the backends

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

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

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

-color <on/off>

Enable color output for diagnostics

-cref, --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 operatons to the specified file

-emit-timing-stats-in-output, --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, --opt-record-file

Create diagnostic yaml file

-print-timing-stats, --print-timing-stats

Print time statistics of various linker operatons 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=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.

17.1.3. 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>, --soname=<name>

Set the internal DT_SONAME field to the specified name

--warn-shared-textrel

Warn if the linker adds a DT_TEXTREL

17.1.4. DYNAMIC LIBRARY/EXECUTABLE OPTIONS

-dynamic-linker <path>

Set the path to the dynamic linker

-export-dynamic, --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, --force-dynamic

Build executable as a force dynamic executable

-no-dynamic-linker, --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

17.1.5. Extended Options

--about

Emit detailed information about the linker

--align-segments

Align segments to page boundaries

--allow-bss-conversion

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

Dont align segments to page boundaries

-no-emit-relocs, --no-emit-relocs

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

Dont reuse trampolines for symbols specified in file

--no-verify

Dont verify link output

--record-command-line

Record the linker command line in the comment section

-reproduce <tarfilename>

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>

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

-rosegment, --rosegment

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

--script-options <matchtype>

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

--use-old-style-trampoline-name

Use old style of naming trampolines

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

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

-L <search_directory>

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

--version

Print the Linker version

17.1.7. Help!

--help, -help

Print option help

--help-hidden, -help-hidden

Print hidden option help

17.1.8. Input Format

-b <input-format>

Specify input format for inputs following this option. Supported values: binary,default

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

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

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

-flto, --flto

Enable LTO if a Bitcode file is present.

-flto-options <option>

Specify various options with LTO

-flto-use-as, --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

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

17.1.13. EXECUTABLE OPTIONS

-L

Path to search for libraries or linker scripts

-Y <path>

Add path to the default library search path

-emit-relocs, --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, --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, --whole-archive

Force load of all members in a static library

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

17.1.15. Misc Features

-archive-member-report <filename>

Emit JSON report for archive members pulled in by symbols

-allow-incompatible-section-mix, --allow-incompatible-section-mix

Allow incompatible section mix

17.1.16. OPTIMIZATION OPTIONS

--eh-frame-hdr

Create EH Frame Header section for faster exception handling

-gc-sections, --gc-sections

Enable garbage collection

-no-gc-sections, --no-gc-sections

Disable garbage collection

--no-merge-strings

Disable String Merging

--no-trampolines

Disable Trampolines

-print-gc-sections, --print-gc-sections

Print sections that are garbage collected

--sframe-hdr

Process and emit .sframe sections for stack unwinding

17.1.17. Features From other Linkers

-R <filename>

Read symbol names and addresses from filename

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

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

17.1.19. SYMBOL RESOLUTION OPTIONS

--allow-multiple-definition

Allow multiple definitions

-allow-shlib-undefined, --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-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, --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-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

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

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

Dont demangle C++ symbols

-portable <symbol>

Specify symbol to be portable wrapped to

--sort-common

sort common symbols by alignment

-sort-common=<option>

Sort common symbols by ascdending/descending order of alignment

--strip-all

Omit all symbol informations from output

--strip-debug

Omit all debug information from output

-wrap <symbol>

Specify symbol to be wrapped to

17.2. Using --start-lib / --end-lib

--start-lib and --end-lib let you pass one or more object files and have ELD treat them as if they were members of an archive for symbol resolution purposes.

Conceptually, ELD packages the object files between --start-lib and --end-lib into an in-memory archive and then processes that archive like a normal .a input.

17.2.1. Thin variant

ELD also supports --start-lib-thin / --end-lib-thin, which packages the enclosed object files into an in-memory thin archive (member paths are stored instead of embedding member bytes).

17.2.2. Linker scripts with archive member patterns

ELD supports using archive member patterns in linker scripts to match inputs from a --start-lib region.

Internally, ELD assigns a synthetic archive name to each --start-lib region: <start-lib:1>, <start-lib:2>, etc., in command-line order. Thin regions use <start-lib-thin:N>. You can reference these synthetic archive names using the standard archive:member pattern syntax in an input section description.

Example:

$ ld.eld main.o --start-lib foo.o bar.o --end-lib -T script.t -MapStyle txt -Map out.map

/* script.t */
SECTIONS {
  .foo_out : { "*<start-lib:1>:*foo.o"(.text*) }
  .bar_out : { "*<start-lib:1>:*bar.o"(.text*) }
}

Notes:

  • The <start-lib:N> names are ELD-specific (they do not correspond to a real on-disk archive).

  • If you need a stable archive name for portability, create a real archive (e.g. with ar cr libname.a ...) and match against *libname.a:*member.o patterns in the script.

17.4. ARM and AArch64 specific options

17.4.1. ARM/AArch64 Linker Options

-compact, --compact

Create a smaller output file. The Loader need to support such files

--disable-bss-conversion

Don’t convert BSS to NonBSS when BSS/NonBSS Sections are mixed

--enable-bss-mixing

Enable mixing BSS/NonBSS sections

--use-mov-veneer

Use movt/movw to load address in veneers with absolute relocation

17.4.2. ARM Linker Option ONLY

-execute-only, --execute-only

Mark executable sections execute-only on AArch64

-fix-cortex-a53-843419, --fix-cortex-a53-843419

Fix the cortex a53 errata 843419

--fix-cortex-a8

Fix the Cortex A8 bug

-fropi, --fropi

Enable Read write data access relative to a static base registers.

-frwpi, --frwpi

Enable Read write data access relative to a static base registers.

--no-fix-cortex-a8

Dont Fix the Cortex A8 bug

-target2 <type>

Interpret R_ARM_TARGET2 as <type>, where <type> is one of abs, rel, or got-rel (default).

17.5. Hexagon specific options

17.5.1. Hexagon Linker experimental Options

--relax

Enable Hexagon Relaxation (default behavior)

-relax=<regex>

Restrict relaxation to only certain sections

17.5.2. Hexagon Options

--gpsize=<maxsize>

Set the maximum size of objects to be optimized using GP

17.6. RISCV specific options

17.6.1. Symbol Patching

--patch-base <value>

Specify base image to generate patch for

--patch-enable

Enable symbol patching using indirection

17.6.2. RISCV Linker Options

--disable-bss-conversion

Don’t convert BSS to NonBSS when BSS/NonBSS Sections are mixed

--enable-bss-mixing

Enable mixing BSS/NonBSS sections

--keep-labels

Keep all local labels for debugging purposes

--no-relax-gp

Disable GP relaxation

--no-relax-tlsdesc

Disable relaxing TLSDESC instruction sequences

--no-relax-zero

Disable zero-page relaxation

--no-relax

Disable relaxation

--no-relax-c

Disable relaxation to compressed instructions

--no-relax-xqci

Disable relaxing to/from Xqci instructions (default behavior)

--relax

Enable relaxation (default behavior)

--relax-xqci

Enable relaxing to/from Xqci instructions

17.7. -z keyword options

The following -z keywords are supported by ELD:

-z combreloc

Combine multiple dynamic relocation sections and sort them to improve dynamic symbol lookup caching.

-z nocombreloc

Disable relocation section combining.

-z global

When building a shared object, make its symbols available for resolution by subsequently loaded libraries.

-z defs

Report unresolved symbol references from regular object files, even when creating a non-symbolic shared library.

-z initfirst

When building a shared object, mark it to be initialized before other objects loaded at the same time, and finalized after them.

-z muldefs

Allow multiple definitions.

-z nocopyreloc

Disable linker-generated .dynbss variables used in place of shared-library variables. This may result in dynamic text relocations.

-z nodefaultlib

Ignore default library search paths when resolving dependencies at runtime.

-z relro

Create a PT_GNU_RELRO segment and request it be made read-only after relocation, if supported. This is disabled by -z norelro.

-z norelro

Do not create a PT_GNU_RELRO segment.

-z lazy

Mark the output for lazy binding (resolve function calls on first use).

-z now

Mark the output for immediate binding (resolve all symbols at load time).

-z origin

Require $ORIGIN handling in rpath/runpath entries.

-z text

Report an error if DT_TEXTREL is set (dynamic relocations in read-only sections).

-z notext

Allow dynamic relocations in read-only sections (do not report DT_TEXTREL).

-z noexecstack

Mark the output as not requiring an executable stack.

-z nognustack

Ignore .note.GNU-stack and do not create PT_GNU_STACK based on it.

-z separate-code

Create a separate code PT_LOAD segment with instructions on pages disjoint from any other data. This is a no-op when a linker script with a SECTIONS command is used.

-z noseparate-code

Disable separate code segment handling. This is the default behavior.

-z execstack

Mark the output as requiring an executable stack.

-z nodelete

Mark a shared object as non-unloadable at runtime.

-z compactdyn

Emit a more compact dynamic section by omitting DT_PLTGOT and DT_DEBUG entries.

-z force-bti

Force GNU property BTI feature bits to be recorded (AArch64).

-z pac-plt

Force GNU property PAC feature bits to be recorded for PLT use (AArch64).

-z common-page-size=<value>

Set the most common page size used for segment alignment and layout optimization.

-z max-page-size=<value>

Set the maximum supported page size used for segment alignment.

17.8. Linker version directive

--enable-linker-version

Enable the GNU linker-script LINKER_VERSION directive. When this option is active, every LINKER_VERSION statement encountered in a linker script emits a NUL-terminated string containing the eld version at that position in the output section. This matches the GNU ld directive and is useful for embedding the linker version directly into a binary. The option applies to the entire link once specified.

--disable-linker-version

Disable the LINKER_VERSION directive. This is the default behaviour, so the directive is parsed but emits no data unless the feature has been explicitly enabled.

17.9. Record command line

--record-command-line

Record the linker command line in the .comment section. This is disabled by default.

--no-record-command-line

Do not record the linker command line in the .comment section.