```{eval-rst}
Compatibility Or Ignored Options
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. option:: -EL

   Link little endian objects.

.. option:: -Qy

   This option is ignored for SVR4 compatibility

.. option:: --Ttext-segment <address>

   Specify an address for the .text-segment segment

.. option:: --add-needed

   Deprecated

.. option:: --allow-shlib-undefined

   Allow undefined symbols from dynamic library when creating executables

.. option:: --copy-dt-needed-entries

   Add the dynamic libraries mentioned to DT_NEEDED

.. option:: -g

   Enable debug output when building shared libraries or executables

.. option:: --hash-size <size>

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

.. option:: --ignore-unknown-opts

   Disable warnings of unimplemented options

.. option:: --map-section <section>

   Specify a input section that maps to a output section

.. option:: --nmagic

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

.. option:: --no-add-needed

   Deprecated

.. option:: --no-allow-shlib-undefined

   Do not allow undefined symbols from dynamic library when creating executables

.. option:: --no-copy-dt-needed-entries

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

.. option:: --plugin <pluginfile>

   Specify a plugin file

.. option:: --plugin-opt <plugin-opt>

   Specify plugin options

.. option:: --rpath-link <path>

   Specifies the path to search

.. option:: -thin-archive-rule-matching-compatibility, --thin-archive-rule-matching-compatibility

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

.. option:: --use-shlib-undefines

   Resolve undefined symbols from dynamic libraries



DIAGNOSITC OPTIONS
^^^^^^^^^^^^^^^^^^^
.. option:: -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
   

.. option:: --color <never/always/auto>

   Enable color output for diagnostics

.. option:: --cref

   Print the references for a symbol or section

.. option:: -t

   Print all files processed by the linker

.. option:: --display-hotness <value>

   Display hotness information for optimization remarks

.. option:: --emit-timing-stats <filename>

   Emit time statistics of various linker operations to the specified file

.. option:: --emit-timing-stats-in-output

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

.. option:: --error-limit <max-error-number>

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

.. option:: --error-style <style>

   Specify an error style, LLVM/GNU

.. option:: --fatal-internal-errors

   Enable fatal internal errors

.. option:: --fatal-warnings

   Enable fatal warnings

.. option:: --gc-cref <symbol/section>

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

.. option:: --no-fatal-internal-errors

   Disable fatal internal errors

.. option:: --no-fatal-warnings

   Disable fatal warnings

.. option:: --no-warn-mismatch

   Do not Warn on incompatible files passed to the linker.

.. option:: --opt-record-file

   Create diagnostic yaml file

.. option:: --print-timing-stats

   Print time statistics of various linker operations to console

.. option:: --progress-bar

   Show Progress Bar

.. option:: --summary

   Display linker run summary at the end

.. option:: --time-region <region>

   Emit time statistics for specified region of linker operation 

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

.. option:: --trace-linker-script

   Trace stages of linker script processing

.. option:: --trace-lto

   Trace stages of lto

.. option:: --trace-merge-strings <option>

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

.. option:: --trace-reloc <relocation>

   trace a particular relocation

.. option:: --trace-section <section_name>

   Show metadata about a particular section

.. option:: -y <symbol>

   Trace a particular symbol

.. option:: --verbose

   Enable verbose output

.. option:: --verbose=<verbose-level>

   Enable verbose output

.. option:: --verify-options <option>

   Verify certain internal linker computations - currently supports reloc

.. option:: --warn-common

   Warn on common symbols

.. option:: --warn-limit <maxwarnings>

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

.. option:: --warn-mismatch

   Warn on incompatible files passed to the linker.



DYNAMIC LIBRARY OPTIONS
^^^^^^^^^^^^^^^^^^^^^^^^
.. option:: --Bgroup

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

.. option:: --Bsymbolic

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

.. option:: --Bsymbolic-functions

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

.. option:: -fPIC

   Enable PIC mode

.. option:: --hash-style <hashstyle>

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

.. option:: --no-warn-shared-textrel

   Don't Warn if the linker adds a DT_TEXTREL

.. option:: --soname <name>

   Set the internal DT_SONAME field to the specified name

.. option:: --warn-shared-textrel

   Warn if the linker adds a DT_TEXTREL



DYNAMIC LIBRARY/EXECUTABLE OPTIONS
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. option:: --default-symver

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

.. option:: --dynamic-linker <path>

   Set the path to the dynamic linker

.. option:: --export-dynamic

   Add all symbols to the dynamic symbol table when creating executables

.. option:: --export-dynamic-symbol <symbol>

   Export specified symbol to dynamic symbol table

.. option:: --force-dynamic

   Build executable as a force dynamic executable

.. option:: --no-dynamic-linker

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

.. option:: --no-export-dynamic

.. option:: --rpath <path>

   Add a path to the runtime library search path



Extended Options
^^^^^^^^^^^^^^^^^
.. option:: --about

   Emit detailed information about the linker

.. option:: --align-segments

   Align segments to page boundaries

.. option:: --allow-bss-conversion

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

.. option:: --copy-farcalls-from-file <filename>

   Copy far calls instead of using trampolines

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

.. option:: --disable-linker-version

   Disable the LINKER_VERSION linker script directive (default)

.. option:: --disable-new-dtags

   Disable new dynamic tags

.. option:: --dump-mapping-file <outputfilename>

   Dump mapping file to output file

.. option:: --dump-response-file <outputfilename>

   Dump response file to output file

.. option:: --emit-relocs-llvm

   Emit relocations sections

.. option:: --enable-linker-version

   Enable the LINKER_VERSION linker script directive

.. option:: --enable-new-dtags

   Enable new dynamic tags

.. option:: --mapping-file <INI-file>

   Reproduce link using a mapping file

.. option:: --no-align-segments

   Don't align segments to page boundaries

.. option:: --no-emit-relocs

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

.. option:: --no-record-command-line

   Do not record the linker command line in the comment section

.. option:: --no-reuse-trampolines-file <filename>

   Don't reuse trampolines for symbols specified in file

.. option:: --no-verify

   Don't verify link output

.. option:: --record-command-line

   Record the linker command line in the comment section

.. option:: --reproduce <tarfilename>|default

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

.. option:: --reproduce-compressed <tarfilename>

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

.. option:: --reproduce-on-fail <tarfilename>|default

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

.. option:: --rosegment

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

.. option:: --script-options <matchtype>

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

.. option:: --use-old-rule-matching

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

.. option:: --use-old-style-trampoline-name

   Use old style of naming trampolines



GENERAL OPTIONS
^^^^^^^^^^^^^^^^
.. option:: --build-id

   Request creation of ".note.gnu.build-id" ELF note section

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

   Request creation of ".note.gnu.build-id" ELF note section

.. option:: --no-warn-rwx-segments

   Silence warnings for segments with RWX permissions

.. option:: -o <outputfile>

   Path to file to write output

.. option:: --repository-version

   Print the Linker Repository version

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

   :option:`-L` ``<search_directory>``

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

.. option:: -v

   Print the Linker version and continue processing

.. option:: --version

   Print the Linker version

.. option:: --warn-rwx-segments

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



Help!
^^^^^^
.. option:: --help

   Print option help

.. option:: --help-hidden

   Print hidden option help



Input Format
^^^^^^^^^^^^^
.. option:: -b <input-format>

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

.. option:: --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>``.

.. option:: --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
   :option:`--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
^^^^^^^^^^^^
.. option:: --Bdynamic

   Link against dynamic library

.. option:: --dynamic

   Create dynamic executable (default)

.. option:: --no-pie

   Do not create a PIE executable

.. option:: --pie

   Create PIE executable

.. option:: -r

   Create relocatable object file

.. option:: --shared

   Create dynamic library

.. option:: --static

   Create static executable



Link Time Speedup
^^^^^^^^^^^^^^^^^^
.. option:: --enable-threads=<option>

   make linker fully threaded, available options: all

.. option:: --no-threads

   Disable Threads at Link time

.. option:: --thread-count <threadcount>

   Specify the number of threads for all linker operations

.. option:: --threads

   Enable Threads at Link time



LLVM and Target Options
^^^^^^^^^^^^^^^^^^^^^^^^
.. option:: -m

   Select target emulation

.. option:: -mabi <mabi>

   Target ABI

.. option:: -march <march>

   Target architecture

.. option:: -mcpu <mcpu>

   Target CPU

.. option:: -mllvm <option>

   Options to pass to LLVM

.. option:: -mtriple <triple>

   Target triple to link for



LTO Options
^^^^^^^^^^^^
.. option:: --disable-verify, -disable-verify

   Do not run the verifier during the optimization pipeline

.. option:: --dwodir <dir>

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

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

.. option:: --fat-lto-objects

   Use .llvm.lto section in fat LTO objects

.. option:: --flto

   Enable LTO if a Bitcode file is present.

.. option:: --flto-options <option>

   Specify various options with LTO

.. option:: --flto-use-as

   Use the standalone assembler instead of the integrated assembler for LTO

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

.. option:: --lto-O<opt-level>

   Optimization level for LTO

.. option:: --lto-cs-profile-file=<value>

   Context sensitive profile file path

.. option:: --lto-cs-profile-generate

   Perform context sensitive PGO instrumentation

.. option:: --lto-debug-pass-manager

   Debug new pass manager

.. option:: --lto-emit-asm

   Emit assembly code

.. option:: --lto-emit-llvm

   Emit LLVM-IR bitcode

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

.. option:: --lto-partitions=<number>

   Number of LTO codegen partitions

.. option:: --lto-sample-profile=<file>

   Sample PGO profile file to be loaded for LTO

.. option:: --no-fat-lto-objects

   Ignore .llvm.lto section in fat LTO objects

.. option:: --opt-remarks-filename <value>

   YAML output file for optimization remarks

.. option:: --opt-remarks-format <value>

   The format used for serializing remarks (default: YAML)

.. option:: --opt-remarks-hotness-threshold <value>

.. option:: --opt-remarks-passes <value>

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

.. option:: --opt-remarks-with-hotness

   Include hotness information in the optimization remarks file

.. option:: --plugin-opt=-<value>, -plugin-opt=-<value>

   Specify an LLVM option for compatibility with LLVMgold.so

.. option:: --plugin-opt=stats-file=<value>, -plugin-opt=stats-file=<value>

   Filename to write LTO statistics to

.. option:: --save-temps

   Save the temporary files produced by LTO

.. option:: --save-temps=<dir>

   Save the temporary files produced by LTO in the directory

.. option:: --thinlto-jobs=<number>

   Number of ThinLTO jobs. Default to --threads=



EXECUTABLE OPTIONS
^^^^^^^^^^^^^^^^^^^
.. option:: -L

   Path to search for libraries or linker scripts

.. option:: -Y <path>

   Add path to the default library search path

.. option:: --emit-relocs

   Make Emit relocs behave just like GNU.

.. option:: -e <symbolname>

   Name of entry point symbol

.. option:: --fini <symbol>

   Specify a finalizer function

.. option:: --image-base <address>

.. option:: --init <symbol>

   Specify an initializer function

.. option:: -l

   Root name of library to use

.. option:: --library=<namespec>

   library to use

.. option:: --no-omagic

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

.. option:: --no-whole-archive

   Restores the default behavior of loading archive members

.. option:: --noinhibit-exec

   Retain the executable output file whenever it is still usable

.. option:: --nostdlib

   Disable default search path for libraries

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

.. option:: --whole-archive

   Force load of all members in a static library



Map Options
^^^^^^^^^^^^
.. option:: --Map <filename>

   Dump the output layout to the map file

.. option:: --MapDetail <option>

   Detail information in the map file

.. option:: --MapStyle <fileformat>

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

.. option:: -M

   Emit the map file

.. option:: --trampoline-map <filename>

   Dump Trampoline Information in YAML format

.. option:: --color-map

   Color the map file



Misc Features
^^^^^^^^^^^^^^
.. option:: --archive-member-report <filename>

   Emit JSON report for archive members pulled in by symbols

.. option:: --emit-symbol-resolution-report <filename>

   Emit JSON symbol resolution report

.. option:: --allow-incompatible-section-mix

   Allow incompatible section mix



OPTIMIZATION OPTIONS
^^^^^^^^^^^^^^^^^^^^^
.. option:: --eh-frame-hdr

   Create EH Frame Header section for faster exception handling

.. option:: --gc-sections

   Enable garbage collection

.. option:: --no-gc-sections

   Disable garbage collection

.. option:: --no-merge-strings

   Disable String Merging

.. option:: --no-trampolines

   Disable Trampolines

.. option:: --print-gc-sections

   Print sections that are garbage collected

.. option:: --sframe-hdr

   Process and emit .sframe sections for stack unwinding



Features From other Linkers
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. option:: -R <filename>

   Read symbol names and addresses from filename

.. option:: --symdef

   Output SymDef file to console

.. option:: --symdef-file <filename>

   Emit SymDef file

.. option:: --symdef-style <style>

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



Plugin Options
^^^^^^^^^^^^^^^
.. option:: --plugin-activity-file <filename>

   Emit plugin activity JSON files

.. option:: --no-default-plugins

   Allow no plugins to be implicitly loaded

.. option:: --plugin-config <config-file>

   Specify a plugin configuration



SYMBOL RESOLUTION OPTIONS
^^^^^^^^^^^^^^^^^^^^^^^^^^
.. option:: --allow-multiple-definition

   Allow multiple definitions

.. option:: --as-needed

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

.. option:: --defsym symbol=<expression>

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

.. option:: --end-group

   End a group

.. option:: --end-lib

   End a library

.. option:: --end-lib-thin

   End a thin library

.. option:: --no-as-needed

   This option restores the default behavior of adding DT_NEEDED entries

.. option:: --no-undefined

   Report unresolved symbol references from regular object files

.. option:: --pop-state

   Restore previously saved input handling flags

.. option:: --push-state

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

.. option:: --start-group

   Start a group

.. option:: --start-lib

   Start a library

.. option:: --start-lib-thin

   Start a thin library

.. option:: -u

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

.. option:: --warn-once

   Warn only once for every undefined reference



SCRIPT OPTIONS
^^^^^^^^^^^^^^^
.. option:: -T <linkerscriptfile>

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

.. option:: --Tbss <address>

   Specify an address for the .bss section

.. option:: --Tdata <address>

   Specify an address for the .data section

.. option:: --Ttext <address>

   Specify an address for the .text section

.. option:: --default-script <pluginfile>

   Use the linker script as the default linker script.

.. option:: --no-check-sections

   Do not check section addresses for overlaps

.. option:: --dynamic-list <list-of-symbols>

   Specify a list of symbols if present will be exported

.. option:: --check-sections

   Check section addresses for overlaps(default)

.. option:: --exclude-libs <libs>

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

.. option:: --extern-list <list-of-symbols>

   Specify a list of symbols that exists as external dependencies

.. option:: --global-merge-non-alloc-strings

   merge non-alloc strings across output sections

.. option:: --orphan-handling <mode>

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

.. option:: --print-memory-usage

   Print memory usage when MEMORY linker script directive is used

.. option:: --section-start <address>

   Specify a virtual output section address for a specified section

.. option:: --sort-section <sort_section>

.. option:: --unique-output-sections

   Place each input section in a unique output section

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

.. option:: --version-script <linkersciptfile>

   Use the linker script as a version script.



SYMBOL OPTIONS
^^^^^^^^^^^^^^^
.. option:: -d

   Assign space to common symbols

.. option:: --demangle

   Demangle C++ symbols

.. option:: --demangle-style <value>

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

.. option:: --discard-all

   Discard all symbols

.. option:: --discard-locals

   Discard all local symbols

.. option:: --no-demangle

   Don't demangle C++ symbols

.. option:: --portable <symbol>

   Specify symbol to be portable wrapped to

.. option:: --sort-common

   sort common symbols by alignment

.. option:: --sort-common=<ascending|descending>

   Sort common symbols by order of alignment

.. option:: --strip-all

   Omit all symbol information from output

.. option:: --strip-debug

   Omit all debug information from output

.. option:: --wrap <symbol>

   Specify symbol to be wrapped to



```