path: root/usr.bin/clang/lld/ld.lld.1

.\"-
.\" Copyright (c) 2018 Kirill Ponomarev
.\" Copyright (c) 2018 The FreeBSD Foundation
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd January 10, 2018
.Dt LD.LLD 1
.Os
.Sh NAME
.Nm ld.lld
.Nd ELF linker from the LLVM project
.Sh SYNOPSIS
.Nm ld.lld
.Op Ar options
.Ar objfile ...
.Sh DESCRIPTION
A linker takes one or more object, archive and library files, and combines
them into an output file (an executable, a shared library, or another object
file).
It relocates code and data from the input files and resolves symbol
references between them.
.Pp
.Nm
is a drop-in replacement for the GNU BFD and gold linkers.
It accepts most of the same command line arguments and linker scripts
as GNU linkers.
.Pp
The following options are available:
.Bl -tag -width indent
.It Fl -allow-multiple-definition
Allow multiple definitions.
.It Fl -as-needed
Only set
.Dv DT_NEEDED
for shared libraries if used.
.It Fl -auxiliary Ar value
Set the
.Dv DT_AUXILIARY
field to the specified name.
.It Fl -Bdynamic
Link against shared libraries.
.It Fl -Bstatic
Do not link against shared libraries.
.It Fl -Bsymbolic-functions
Bind defined function symbols locally.
.It Fl -Bsymbolic
Bind defined symbols locally.
.It Fl -build-id= Ns Ar value
Generate a build ID note.
.It Fl -build-id
Generate a build ID note.
.It Fl -color-diagnostics= Ns Ar value
Use colors in diagnostics.
.It Fl -color-diagnostics
Use colors in diagnostics.
.It Fl -compress-debug-sections= Ns Ar value
Compress DWARF debug sections.
.It Fl -define-common
Assign space to common symbols.
.It Fl -defsym= Ns Ar value
Define a symbol alias.
.It Fl -demangle
Demangle symbol names.
.It Fl -disable-new-dtags
Disable new dynamic tags.
.It Fl -discard-all
Delete all local symbols.
.It Fl -discard-locals
Delete temporary local symbols.
.It Fl -discard-none
Keep all symbols in the symbol table.
.It Fl -dynamic-linker Ar value
Specify the dynamic linker to be used for a dynamically linked executable.
This is recorded in an ELF segment of type
.Dv PT_INTERP .
.It Fl -dynamic-list Ar value
Read a list of dynamic symbols.
.It Fl -eh-frame-hdr
Request creation of
.Li .eh_frame_hdr
section and
.Dv PT_GNU_EH_FRAME
segment header.
.It Fl -emit-relocs
Generate relocations in the output.
.It Fl -enable-new-dtags
Enable new dynamic tags.
.It Fl -end-lib
End a grouping of objects that should be treated as if they were together
in an archive.
.It Fl -entry Ar entry
Name of entry point symbol.
.It Fl -error-limit Ar value
Maximum number of errors to emit before stopping.
A value of zero indicates that there is no limit.
.It Fl -error-unresolved-symbols
Report unresolved symbols as errors.
.It Fl -exclude-libs Ar value
Exclude static libraries from automatic export.
.It Fl -export-dynamic-symbol Ar value
Put a symbol in the dynamic symbol table.
.It Fl -export-dynamic
Put symbols in the dynamic symbol table.
.It Fl -fatal-warnings
Treat warnings as errors.
.It Fl -filter= Ns Ar value
Set the
.Dv DT_FILTER
field to the specified value.
.It Fl -fini Ar symbol
Specify a finalizer function.
.It Fl -format= Ns Ar input-format
Change the input format of the inputs following this option.
.It Fl -full-shutdown
Perform a full shutdown instead of calling
.Fn _exit .
.It Fl -gc-sections
Enable garbage collection of unused sections.
.It Fl -gdb-index
Generate
.Li .gdb_index
section.
.It Fl -hash-style Ar value
Specify hash style (sysv, gnu or both).
.It Fl -help
Print a usage message.
.It Fl -icf=all
Enable identical code folding.
.It Fl -icf=none
Disable identical code folding.
.It Fl -image-base= Ns Ar value
Set the base address to
.Ar value .
.It Fl -init Ar symbol
Specify an initializer function.
.It Fl -lto-aa-pipeline= Ns Ar value
AA pipeline to run during LTO.
Used in conjunction with
.Fl -lto-newpm-passes .
.It Fl -lto-newpm-passes= Ns Ar value
Passes to run during LTO.
.It Fl -lto-O Ar opt-level
Optimization level for LTO.
.It Fl -lto-partitions= Ns Ar value
Number of LTO codegen partitions.
.It Fl L Ar dir
Add a directory to the library search path.
.It Fl l Ar libName
Root name of library to use.
.It Fl -Map Ar value
Print a link map to the specified file.
.It Fl m Ar value
Set target emulation.
.It Fl -no-as-needed
Always set
.Dv DT_NEEDED
for shared libraries.
.It Fl -no-color-diagnostics
Do not use colors in diagnostics.
.It Fl -no-define-common
Do not assign space to common symbols.
.It Fl -no-demangle
Do not demangle symbol names.
.It Fl -no-dynamic-linker
Inhibit output of an
.Li .interp
section.
.It Fl -no-gc-sections
Disable garbage collection of unused sections.
.It Fl -no-gnu-unique
Disable STB_GNU_UNIQUE symbol binding.
.It Fl -no-rosegment
Do not put read-only non-executable sections in their own segment.
.It Fl -no-threads
Do not run the linker multi-threaded.
.It Fl -no-undefined-version
Report version scripts that refer undefined symbols.
.It Fl -no-undefined
Report unresolved symbols even if the linker is creating a shared library.
.It Fl -no-whole-archive
Restores the default behavior of loading archive members.
.It Fl -noinhibit-exec
Retain the executable output file whenever it is still usable.
.It Fl -nopie
Do not create a position independent executable.
.It Fl -nostdlib
Only search directories specified on the command line.
.It Fl -oformat Ar format
Specify the binary format for the output object file.
.It Fl -omagic
Set the text and data sections to be readable and writable.
.It Fl -opt-remarks-filename Ar value
YAML output file for optimization remarks.
.It Fl -opt-remarks-with-hotness
Include hotness information in the optimization remarks file.
.It Fl O Ar value
Optimize output file size.
.It Fl o Ar path
Write the output executable, library or object to
.Ar path .
If not specified,
.Dv a.out
is used as a default.
.It Fl -pie
Create a position independent executable.
.It Fl -print-gc-sections
List removed unused sections.
.It Fl -print-map
Print a link map to the standard output.
.It Fl -relocatable
Create relocatable object file.
.It Fl -reproduce Ar value
Dump linker invocation and input files for debugging.
.It Fl -retain-symbols-file= Ns Ar file
Retain only the symbols listed in the file.
.It Fl -rpath Ar value
Add a
.Dv DT_RUNPATH
to the output.
.It Fl -rsp-quoting= Ns Ar value
Quoting style for response files.
The supported values are
.Ar windows
and
.Ar posix .
.It Fl -script Ar value
Read linker script from the path
.Ar value .
.It Fl -section-start Ar address
Set address of section.
.It Fl -shared
Build a shared object.
.It Fl -soname= Ns Ar value
Set
.Dv DT_SONAME
to
.Ar value .
.It Fl -sort-section Ar value
Specifies sections sorting rule when linkerscript is used.
.It Fl -start-lib
Start a grouping of objects that should be treated as if they were together
in an archive.
.It Fl -strip-all
Strip all symbols.
.It Fl -strip-debug
Strip debugging information.
.It Fl -symbol-ordering-file Ar value
Lay out sections in the order specified by the symbol file.
.It Fl -sysroot= Ns Ar value
Set the system root.
.It Fl -target1-abs
Interpret
.Dv R_ARM_TARGET1
as
.Dv R_ARM_ABS32 .
.It Fl -target1-rel
Interpret
.Dv R_ARM_TARGET1
as
.Dv R_ARM_REL32 .
.It Fl -target2=type
Interpret
.Dv R_ARM_TARGET2
as
.Ar type ,
where
.Ar type
is one of
.Li rel ,
.Li abs ,
or
.Li got-rel .
.It Fl -Tbss Ar value
Same as
.Fl -section-start
with
.Li .bss
as the sectionname.
.It Fl -Tdata Ar value
Same as
.Fl -section-start
with
.Li .data
as the sectionname.
.It Fl -thinlto-cache-dir= Ns Ar value
Path to ThinLTO cached object file directory.
.It Fl -thinlto-cache-policy Ar value
Pruning policy for the ThinLTO cache.
.It Fl -thinlto-jobs= Ns Ar value
Number of ThinLTO jobs.
.It Fl -threads
Run the linker multi-threaded.
.It Fl -trace-symbol Ar value
Trace references to symbols.
.It Fl -trace
Print the names of the input files.
.It Fl -Ttext Ar value
Same as
.Fl -section-start
with
.Li .text
as the sectionname.
.It Fl -undefined Ar value
Force undefined symbol during linking.
.It Fl -unresolved-symbols= Ns Ar value
Determine how to handle unresolved symbols.
.It Fl -verbose
Verbose mode.
.It Fl -version-script Ar value
Read a version script.
.It Fl V , Fl -version
Display the version number and exit.
.It Fl v
Display the version number, and proceed with linking if object files are
specified.
.It Fl -warn-common
Warn about duplicate common symbols.
.It Fl -warn-unresolved-symbols
Report unresolved symbols as warnings.
.It Fl -whole-archive
Force load of all members in a static library.
.It Fl -wrap Ar symbol
Use wrapper functions for symbol.
.It Fl z Ar option
Linker option extensions.
.Bl -tag -width indent
.It Cm notext
Allow relocations against read-only segments.
Sets the
.Dv DT_TEXTREL flag in the
.Dv DYNAMIC
section.
.It Cm text
Do not allow relocations against read-only segments.
This is the default.
.El
.El
.Sh IMPLEMENTATION NOTES
The targets supported by
.Nm
are:
elf32-i386 elf32-iamcu elf32-littlearm elf32-ntradbigmips elf32-ntradlittlemips elf32-powerpc elf32-tradbigmips elf32-tradlittlemips elf32-x86-64 elf64-amdgpu elf64-littleaarch64 elf64-powerpc elf64-tradbigmips elf64-tradlittlemips elf64-x86-64