lld: introduce basic man page
Upstream lld has no man page. Introduce a basic one for FreeBSD based on ld.lld --help, with a brief introduction and additional detail for some options. We'll continue refining this in FreeBSD, and then submit it upstream once the first round of edits are complete. Submitted by: krion, Arshan Khanifar, emaste, bjk MFC after: 2 weeks Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D13813
This commit is contained in:
Ed Maste
parent
00da6aa72b
commit
71e8c9b65d
@ -7,9 +7,10 @@ LLD_SRCS= ${LLVM_SRCS}/tools/lld
|
||||
|
||||
PACKAGE= lld
|
||||
PROG_CXX= ld.lld
|
||||
MAN=
|
||||
|
||||
.if ${MK_LLD_IS_LD} != "no"
|
||||
SYMLINKS= ${PROG_CXX} ${BINDIR}/ld
|
||||
MLINKS= ld.lld.1 ld.1
|
||||
.endif
|
||||
|
||||
CFLAGS+= -I${LLD_SRCS}/ELF
|
||||
|
||||
364
usr.bin/clang/lld/ld.lld.1
Normal file
364
usr.bin/clang/lld/ld.lld.1
Normal file
@ -0,0 +1,364 @@
|
||||
.\"-
|
||||
.\" 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
|
||||
Loading…
Reference in New Issue
Block a user