= Introduction =

[[https://lld.llvm.org/|lld]], part of the LLVM family of projects, is a high-performance linker for the ELF, COFF, and Mach-O object formats. This page describes the now-completed project to use lld as FreeBSD's base system linker.

== LLD in Base ==

As of 13, lld is now the default system linker on all supported architectures.

Prior to this, lld was in use on i386, amd64, arm*, aarch64, and riscv64*, with other architectures still using GNU BFD ld. For more information, see arch(7) in the manual for your particular FreeBSD version.

To forcibly build world and kernel with LLD and install LLD as /usr/bin/ld in pre-13 versions, add to /etc/src.conf:
{{{
WITH_LLD_IS_LD=yes
WITH_LLD_BOOTSTRAP=yes
}}}
{{{WITH_LLD_BOOTSTRAP=yes}}} uses lld as the linker for building the FreeBSD world, and has no effect on the linker installed in {{{/usr/bin/ld}}}. {{{WITH_LLD_IS_LD=yes}}} installes lld as {{{/usr/bin/ld}}}, and has no effect on the linker used for building world.

= Historical Issues =

== LLD patches ==

 * --([[https://reviews.llvm.org/D41037 | Create reserved symbols early so they can be versioned ]])--

'''MIPS'''
 * --([[https://reviews.llvm.org/D31528 | MIPS Multi-GOT implementation]] (2017-03-31))--
'''ARM'''
 * --([[https://reviews.llvm.org/D37743 | Record created ThunkSections in InputSectionDescription]] (2017-09-12))--
 * --([[https://reviews.llvm.org/D34689 | Pre-create ThunkSections at Target specific intervals]] (2017-06-27))--
 * --([[https://reviews.llvm.org/D34691 | Introduce range extension thunks for ARM]] (2017-06-27))--
 * --([[https://reviews.llvm.org/D34692 | Add support for multiple passes to createThunks]] (2017-06-27))--

== Ports ==

A FreeBSD ports exp-run is tracked in [[https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=214864|PR214864]].

 * go crashes on startup [[https://github.com/golang/go/issues/19018|go Github issue 19018]]
 * print/gl2ps needs explicit -L/usr/lib [[https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=218399|PR218399]].

Common issues in ports:

 1. Passing compiler flags, such as {{{-fPIC}}}, to the linker.
 2. lld has no built-in search paths ({{{/lib, /usr/lib}}}). Normally the linker is invoked from the compiler driver, which adds the library search paths. If lld is invoked directly then library search paths must be explicitly specified, with {{{-L/lib -L/usr/lib}}}.
 3. Shared library protected symbol preemption.
 4. lld does not have a built-in default output target. For the most common use of the linker (linking individual .o objects in to an executable or shared object) lld infers the target from the first object file. However, when the linker is used to convert an arbitrary binary file into an ELF object (via -r -b binary) lld must have the output target specified explicitly with -m.

= Resources =

 * Rui Ueyama's [[https://www.youtube.com/watch?v=CYCRqjVa6l4|New LLD linker for ELF]] talk
 * [[http://lists.llvm.org/pipermail/llvm-dev/2016-March/096449.html|Linking the FreeBSD base system with LLD]] status update from March 2016
 * [[https://docs.google.com/document/d/1GcTY7kDKmvSYFAkJdUjLbHwoMHZlpbGG49wdWuaEnrg/edit?usp=sharing|lld as the FreeBSD base system linker]] Google Doc
----
CategoryHistorical
CategoryProject