Add initial ld.lld.1 man page

[emaste]

Summary

One of our requirements in FreeBSD to enable lld as the system linker was that it has a man page. We created the man page in this review, and offer it for inclusion upstream.

Some options are missing detail, but it should make a good starting point.

[emaste]

• Update copyright and license statement
• Remove internal -full-shutdown option

[krytarowski]

docs/ld.lld.1

5

Can we put this to .Sh HISTORY?

[ruiu]

Thank you for doing this!

docs/ld.lld.1

49

"md5", "sha1", "tree", "uuid", 0x<hexstring> (e.g. 0xdeadbeef) and "none" are accepted. tree is a synonym to sha1.

53–56

-color-diagnostics={auto,always,never}

• "auto" enables color output only when output is a terminal. It disables color output if the output is not a terminal (it uses isatty() internally.)

-color-diagnostics is a synonym to -color-diagnostics=auto

57

-compress-debug-sections={none,zlib}

If zlib is specified, lld compresses debug sections in output.

61

-defsym=symbol=expression

expression can either be another symbol or a linker script expression. E.g.

-defsym=foo=bar
-defysm=foo=bar+0x100

122

both is default.

182

-no-pie

(-nopie was a typo and I recently fixed that.)

186–192

--oformat, --omagic, --opt-remarks-filename and --opt-remarks-with-hotness. An option that starts with "o" must be preceded by two dashes. Otherwise it's interpreted as -o foo (output file).

[emaste]

Incorporate review feedback

[emaste]

docs/ld.lld.1

186–192

Fl renders the first dash, so Fl -omagic renders as --omagic.

[emaste]

PDF rendered version of the man page:

ld.lld.pdf16 KBDownload

[emaste]

docs/ld.lld.1

5

It seems excessive to create a .Sh HISTORY section containing only the history of the man page itself; this could perhaps be fleshed out in a subsequent commit with more history of lld and adoption in various projects?

[ruiu]

docs/ld.lld.1

115

value is a filename, and this option reads a list of dynamic symbols from a given file.

139

value is a symbol.

152

input-format is one of binary, elf or default. default is synonym for elf.

194

value is a filename.

232

Currently a format must be "binary" if this option is given, and when the option is given, it outputs an ELF header-less file.

236

value is a filename.

240–241

O0 disables string merging. O1 enables string merging. O2 enables string tail merging. O1 is the default.

270

value is a filename.

291

Ditto

336

This is the default.

337

value is a symbol name.

347

value is a symbol name.

353

value is a filename.

373

stack-size value
Set PT_GNU_STACK to a given value

max-page-size value
Override the system default maximum page size to a given value

muls
Synonym for --allow-multiple-definition

nocombreloc
Do not sort relocation section contents

execstack
Make the stack executable

nocopyreloc
Treat copy relocations as errors

nodelete
Set DF_1_NODELETE bit in DT_FLAGS_1 to 1

nodlopen
Set DF_1_NOOPEN bit in DT_FLAGS_1 to 1

now
Set DF_BIND_NOW bit

origin
Set DF_ORIGIN bit

norelro
Do not emit PT_GNU_RELRO segment

retpolineplt
Emit a PLT that mitigates Spectre v2 vulnerability

rodynamic
Make .dynamic section read-only

wxneeded
Create a PT_OPENBSD_WXNEEDED segment

[grimar]

docs/ld.lld.1

386

Is "The targets supported by" part needed ? Please see comments for D42952 and D42992, we
changed help to print just "elf" instead.
(and btw, this list has 2 missing targets currently as mentioned in description of D42952).

[emaste]

docs/ld.lld.1

232

Should we accept elf also?

[emaste]

• more feedback from review
• incorporated doc updates for -z from https://reviews.freebsd.org/D14220

[emaste]

PDF version of current version:

ld.lld.pdf18 KBDownload

[emaste]

docs/ld.lld.1

409

Not sure how this 稙 character ended up here, but it is fixed locally.

[krytarowski]

docs/ld.lld.1

5

I propose something like this:

.Sh HISTORY
This man page first appeared in
.Fx .
.Sh AUTHORS
.An Ed Maste Aq Mt [e-mail]

A hidden comment has little added value.

[ruiu]

Looking pretty good! LGTM

docs/ld.lld.1

267

01 -> O1
02 -> O2

[emaste]

Thanks, I'll commit this later today. Not sure how I ended up with 01 instead of O1 but have fixed those locally.

I'd to have an "implementation details" section explaining (at least) the way lld does symbol resolution and how it differs from bfd/gold but that can be a later commit; perhaps you have notes from one of your talks already that could be dropped in.

[emaste]

docs/ld.lld.1

5

I'll come back to this for a future commit.

docs/ld.lld.1

+.\" This file is distributed under the University of Illinois Open Source
+.\" License. See LICENSE.TXT for details.
+.\"
+.\" This man page documents only lld's ELF linking support, obtained originally
+.\" from FreeBSD.
+.Dd February 7, 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
+These options are available:
+.Bl -tag -width indent
+.It Fl -allow-multiple-definition
+Do not error if a symbol is defined multiple times.
+The first definition will be used.
+.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.
+.Ar value
+may be one of
+.Cm md5 ,
+.Cm sha1 ,
+.Cm tree ,
+.Cm uuid ,
+.Cm 0x Ns Ar hex-string ,
+and
+.Cm none .
+.Cm tree
+is an alias for
+.Cm sha1 .
+Build-IDs of type
+.Cm md5 ,
+.Cm sha1 ,
+and
+.Cm tree
+are calculated from the object contents.
+.It Fl -build-id
+Generate a build ID note.
+.It Fl -color-diagnostics= Ns Ar value
+Use colors in diagnostics.
+.Ar value
+may be one of
+.Cm always ,
+.Cm auto ,
+and
+.Cm never .
+.Cm auto
+enables color if and only if output is to a terminal.
+.It Fl -color-diagnostics
+Alias for
+.Fl -color-diagnostics= Ns Cm auto .
+.It Fl -compress-debug-sections= Ns Ar value
+Compress DWARF debug sections.
+.Ar value
+may be
+.Cm none
+or
+.Cm zlib .
+.It Fl -define-common
+Assign space to common symbols.
+.It Fl -defsym= Ns Ar symbol= Ns Ar expression
+Define a symbol alias.
+.Ar expression
+may be another symbol or a linker script expression.
+For example,
+.Fl -defsym= Ns Cm foo= Ns Cm bar
+or
+.Fl -defsym= Ns Cm foo= Ns Cm bar+0x100 .
+.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 file
+Read a list of dynamic symbols from
+.Ar file .
+.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 symbol
+Include
+.Ar 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
+Specify the format of the inputs following this option.
+.Ar input-format
+may be one of
+.Cm binary ,
+.Cm elf ,
+and
+.Cm default .
+.Cm default
+is a synonym for
+.Cm elf .
+.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.
+.Ar value
+may be
+.Cm sysv ,
+.Cm gnu ,
+or
+.Cm both .
+.Cm both
+is the default.
+.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 file
+Print a link map to
+.Ar 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 -no-pie
+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 format for the output object file.
+The only supported
+.Ar format
+is
+.Cm binary ,
+which produces output with no ELF header.
+.It Fl -omagic
+Set the text and data sections to be readable and writable.
+.It Fl -opt-remarks-filename Ar file
+Write optimization remarks in YAML format to
+.Ar file .
+.It Fl -opt-remarks-with-hotness
+Include hotness information in the optimization remarks file.
+.It Fl O Ar value
+Optimize output file size.
+.Ar value
+may be:
+.Bl -tag -width indent
+.It Cm O0
+Disable string merging.
+.It Cm O1
+Enable string merging.
+.It Cm O2
+Enable string tail merging.
+.El
+.Cm O1
+is the default.
+.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 file
+Read linker script from
+.Ar file .
+.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 file
+Lay out sections in the order specified by
+.Ar 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.
+This option is enabled by default.
+.It Fl -trace-symbol Ar symbol
+Trace references to
+.Ar symbol .
+.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 symbol
+Force
+.Ar symbol
+to be an 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 file
+Read version script from
+.Ar file .
+.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 execstack
+Make the main stack executable.
+Stack permissions are recorded in the
+.Dv PT_GNU_STACK
+segment.
+.It Cm muldefs
+Do not error if a symbol is defined multiple times.
+The first definition will be used.
+This is a synonym for
+.Fl -allow-multiple-definition.
+.It Cm nocombreloc
+Disable combining and sorting multiple relocation sections.
+.It Cm nocopyreloc
+Disable the creation of copy relocations.
+.It Cm nodelete
+Set the
+.Dv DF_1_NODELETE
+flag to indicate that the object cannot be unloaded from a process.
+.It Cm nodlopen
+Set the
+.Dv DF_1_NOOPEN
+flag to indcate that the object may not be opened by
+.Xr dlopen 3 .
+.It Cm norelro
+Do not indicate that portions of the object shold be mapped read-only
+after initial relocation processing.
+The object will omit the
+.Dv PT_GNU_RELRO
+segment.
+.It Cm notext
+Allow relocations against read-only segments.
+Sets the
+.Dv DT_TEXTREL flag in the
+.Dv DYNAMIC
+section.
+.It Cm now
+Set the
+.Dv DF_BIND_NOW
+flag to indicate that the run-time loader should perform all relocation
+processing as part of object initialization.
+By default relocations may be performed on demand.
+.It Cm origin
+Set the
+.Dv DF_ORIGIN
+flag to indicate that the object requires
+$ORIGIN
+processing.
+.It Cm retpolineplt
+Emit retpoline format PLT entries as a mitigation for CVE-2017-5715.
+.It Cm rodynamic
+Make the
+.Li .dynamic
+section read-only.
+The
+.Dv DT_DEBUG
+tag will not be emitted.
+.It Cm stack-size= Ns Ar size
+Set the main thread's stack size to
+.Ar size .
+The stack size is recorded as the size of the
+.Ar size .
+.Dv PT_GNU_STACK
+program segment.
+.It Cm text
+Do not allow relocations against read-only segments.
+This is the default.
+.It Cm wxneeded
+Create a
+.Dv PT_OPENBSD_WXNEEDED
+segment.
+.El
+.El