[PATCH] D42963: Add initial ld.lld.1 man page

Tue Feb 6 19:00:49 PST 2018

This still has an entry for -as-needed and one for -no-as-needed.

Cheers,
Rafael

Ed Maste via Phabricator <reviews at reviews.llvm.org> writes:

> emaste updated this revision to Diff 133124.
> emaste added a comment.
>
> Incorporate review feedback
>
>
> https://reviews.llvm.org/D42963
>
> Files:
>   docs/ld.lld.1
>
> Index: docs/ld.lld.1
> ===================================================================
> --- /dev/null
> +++ docs/ld.lld.1
> @@ -0,0 +1,385 @@
> +.\" 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 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
> +These 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.
> +.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 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 -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 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 -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 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