On Thu, Mar 01, 2018 at 06:15:59PM +1100, Jonathan Gray wrote:
> From lld svn rev 324739 with -z muldefs and -z retpolineplt text removed
> to match lld 5.0.1.
> 

morning.

this will replace the ld page for archs building llvm, right? haven;t
the stomach to read it yet, but no objections. you should probably add
an Nm entry to NAME for "ld" though:

        .Sh NAME
        .Nm ld.lld ,
        .Nm ld

also don;t know if you tag this stuff $OpenBSD$ or not.

jmc

> Index: usr.bin/clang/lld/Makefile
> ===================================================================
> RCS file: /cvs/src/gnu/usr.bin/clang/lld/Makefile,v
> retrieving revision 1.11
> diff -u -p -r1.11 Makefile
> --- usr.bin/clang/lld/Makefile        4 Oct 2017 20:57:10 -0000       1.11
> +++ usr.bin/clang/lld/Makefile        1 Mar 2018 05:50:09 -0000
> @@ -5,17 +5,18 @@
>  PROG=        ld.lld
>  BINDIR=      /usr/bin
>  SRCS=        lld.cpp
> -NOMAN=
>  
>  TARGET_ARCH?=        ${MACHINE_ARCH}
>  .if ${TARGET_ARCH} == "aarch64"
>  LINKS=       ${BINDIR}/ld.lld ${BINDIR}/ld
> +MLINKS=      ld.lld.1 ld.1
>  .endif
>  
>  CPPFLAGS+=   ${CLANG_INCLUDES}
>  CPPFLAGS+=   -I${.CURDIR}/../../../llvm/tools/lld/include
>  
>  .PATH:       ${.CURDIR}/../../../llvm/tools/lld/tools/lld
> +.PATH:       ${.CURDIR}/../../../llvm/tools/lld/docs
>  
>  LLVM_LIBDEPS=        lldELF \
>               lldConfig \
> Index: llvm/tools/lld/docs/ld.lld.1
> ===================================================================
> RCS file: llvm/tools/lld/docs/ld.lld.1
> diff -N llvm/tools/lld/docs/ld.lld.1
> --- /dev/null 1 Jan 1970 00:00:00 -0000
> +++ llvm/tools/lld/docs/ld.lld.1      1 Mar 2018 05:23:10 -0000
> @@ -0,0 +1,518 @@
> +.\" 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 9, 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 fast ,
> +.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 fast ,
> +.Cm md5 ,
> +.Cm sha1 ,
> +and
> +.Cm tree
> +are calculated from the object contents.
> +.Cm fast
> +is not intended to be cryptographically secure.
> +.It Fl -build-id
> +Synonym for
> +.Fl -build-id= Ns Cm fast .
> +.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 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 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
> +.Sh IMPLEMENTATION NOTES
> +.Nm Ap s
> +handing of archive files (those with a
> +.Cm .a
> +file extension) is different from traditional linkers used on Unix-like
> +systems.
> +.Pp
> +Traditional linkers maintain a set of undefined symbols during linking.
> +The linker processes each file in the order in which it appears on the
> +command line, until the set of undefined symbols becomes empty.
> +An object file is linked into the output object when it is encountered,
> +with its undefined symbols added to the set.
> +Upon encountering an archive file a traditional linker searches the objects
> +contained therein, and processes those that satisfy symbols in the unresolved
> +set.
> +.Pp
> +Handling mutually dependent archives may be awkward when using a traditional
> +linker.
> +Archive files may have to be specified multiple times, or the special command
> +line options
> +.Fl -start-group
> +and
> +.Fl -end-group
> +may be used to have the linker loop over the files in the group until no new
> +symbols are added to the set.
> +.Pp
> +.Nm
> +records all symbols found in objects and archives as it iterates over
> +command line arguments.
> +When
> +.Nm
> +encounters an undefined symbol that can be resolved by an object file
> +contained in a previously processed archive file, it immediately extracts
> +and links it into the output object.
> +.Pp
> +With certain archive inputs
> +.Nm
> +may produce different results compared to traditional linkers.
> +In practice, large bodies of third party software have been linked with
> +.Nm
> +without material issues.
> 

Reply via email to