1LLD - The LLVM Linker 2===================== 3 4LLD is a linker from the LLVM project that is a drop-in replacement 5for system linkers and runs much faster than them. It also provides 6features that are useful for toolchain developers. 7 8The linker supports ELF (Unix), PE/COFF (Windows), Mach-O (macOS) and 9WebAssembly in descending order of completeness. Internally, LLD consists of 10several different linkers. The ELF port is the one that will be described in 11this document. The PE/COFF port is complete, including 12Windows debug info (PDB) support. The WebAssembly port is still a work in 13progress (See :doc:`WebAssembly`). The Mach-O port is built based on a 14different architecture than the others. For the details about Mach-O, please 15read :doc:`AtomLLD`. 16 17Features 18-------- 19 20- LLD is a drop-in replacement for the GNU linkers that accepts the 21 same command line arguments and linker scripts as GNU. 22 23 We are currently working closely with the FreeBSD project to make 24 LLD default system linker in future versions of the operating 25 system, so we are serious about addressing compatibility issues. As 26 of February 2017, LLD is able to link the entire FreeBSD/amd64 base 27 system including the kernel. With a few work-in-progress patches it 28 can link approximately 95% of the ports collection on AMD64. For the 29 details, see `FreeBSD quarterly status report 30 <https://www.freebsd.org/news/status/report-2016-10-2016-12.html#Using-LLVM%27s-LLD-Linker-as-FreeBSD%27s-System-Linker>`_. 31 32- LLD is very fast. When you link a large program on a multicore 33 machine, you can expect that LLD runs more than twice as fast as the GNU 34 gold linker. Your mileage may vary, though. 35 36- It supports various CPUs/ABIs including AArch64, AMDGPU, ARM, Hexagon, MIPS 37 32/64 big/little-endian, PowerPC, PowerPC64, RISC-V, SPARC V9, x86-32 and 38 x86-64. Among these, AArch64, ARM (>= v6), PowerPC, PowerPC64, x86-32 and 39 x86-64 have production quality. MIPS seems decent too. 40 41- It is always a cross-linker, meaning that it always supports all the 42 above targets however it was built. In fact, we don't provide a 43 build-time option to enable/disable each target. This should make it 44 easy to use our linker as part of a cross-compile toolchain. 45 46- You can embed LLD in your program to eliminate dependencies on 47 external linkers. All you have to do is to construct object files 48 and command line arguments just like you would do to invoke an 49 external linker and then call the linker's main function, 50 ``lld::elf::link``, from your code. 51 52- It is small. We are using LLVM libObject library to read from object 53 files, so it is not a completely fair comparison, but as of February 54 2017, LLD/ELF consists only of 21k lines of C++ code while GNU gold 55 consists of 198k lines of C++ code. 56 57- Link-time optimization (LTO) is supported by default. Essentially, 58 all you have to do to do LTO is to pass the ``-flto`` option to clang. 59 Then clang creates object files not in the native object file format 60 but in LLVM bitcode format. LLD reads bitcode object files, compile 61 them using LLVM and emit an output file. Because in this way LLD can 62 see the entire program, it can do the whole program optimization. 63 64- Some very old features for ancient Unix systems (pre-90s or even 65 before that) have been removed. Some default settings have been 66 tuned for the 21st century. For example, the stack is marked as 67 non-executable by default to tighten security. 68 69Performance 70----------- 71 72This is a link time comparison on a 2-socket 20-core 40-thread Xeon 73E5-2680 2.80 GHz machine with an SSD drive. We ran gold and lld with 74or without multi-threading support. To disable multi-threading, we 75added ``-no-threads`` to the command lines. 76 77============ =========== ============ ==================== ================== =============== ============= 78Program Output size GNU ld GNU gold w/o threads GNU gold w/threads lld w/o threads lld w/threads 79ffmpeg dbg 92 MiB 1.72s 1.16s 1.01s 0.60s 0.35s 80mysqld dbg 154 MiB 8.50s 2.96s 2.68s 1.06s 0.68s 81clang dbg 1.67 GiB 104.03s 34.18s 23.49s 14.82s 5.28s 82chromium dbg 1.14 GiB 209.05s [1]_ 64.70s 60.82s 27.60s 16.70s 83============ =========== ============ ==================== ================== =============== ============= 84 85As you can see, lld is significantly faster than GNU linkers. 86Note that this is just a benchmark result of our environment. 87Depending on number of available cores, available amount of memory or 88disk latency/throughput, your results may vary. 89 90.. [1] Since GNU ld doesn't support the ``-icf=all`` and 91 ``-gdb-index`` options, we removed them from the command line 92 for GNU ld. GNU ld would have been slower than this if it had 93 these options. 94 95Build 96----- 97 98If you have already checked out LLVM using SVN, you can check out LLD 99under ``tools`` directory just like you probably did for clang. For the 100details, see `Getting Started with the LLVM System 101<https://llvm.org/docs/GettingStarted.html>`_. 102 103If you haven't checked out LLVM, the easiest way to build LLD is to 104check out the entire LLVM projects/sub-projects from a git mirror and 105build that tree. You need `cmake` and of course a C++ compiler. 106 107.. code-block:: console 108 109 $ git clone https://github.com/llvm/llvm-project llvm-project 110 $ mkdir build 111 $ cd build 112 $ cmake -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS=lld -DCMAKE_INSTALL_PREFIX=/usr/local ../llvm-project/llvm 113 $ make install 114 115Using LLD 116--------- 117 118LLD is installed as ``ld.lld``. On Unix, linkers are invoked by 119compiler drivers, so you are not expected to use that command 120directly. There are a few ways to tell compiler drivers to use ld.lld 121instead of the default linker. 122 123The easiest way to do that is to overwrite the default linker. After 124installing LLD to somewhere on your disk, you can create a symbolic 125link by doing ``ln -s /path/to/ld.lld /usr/bin/ld`` so that 126``/usr/bin/ld`` is resolved to LLD. 127 128If you don't want to change the system setting, you can use clang's 129``-fuse-ld`` option. In this way, you want to set ``-fuse-ld=lld`` to 130LDFLAGS when building your programs. 131 132LLD leaves its name and version number to a ``.comment`` section in an 133output. If you are in doubt whether you are successfully using LLD or 134not, run ``readelf --string-dump .comment <output-file>`` and examine the 135output. If the string "Linker: LLD" is included in the output, you are 136using LLD. 137 138History 139------- 140 141Here is a brief project history of the ELF and COFF ports. 142 143- May 2015: We decided to rewrite the COFF linker and did that. 144 Noticed that the new linker is much faster than the MSVC linker. 145 146- July 2015: The new ELF port was developed based on the COFF linker 147 architecture. 148 149- September 2015: The first patches to support MIPS and AArch64 landed. 150 151- October 2015: Succeeded to self-host the ELF port. We have noticed 152 that the linker was faster than the GNU linkers, but we weren't sure 153 at the time if we would be able to keep the gap as we would add more 154 features to the linker. 155 156- July 2016: Started working on improving the linker script support. 157 158- December 2016: Succeeded to build the entire FreeBSD base system 159 including the kernel. We had widen the performance gap against the 160 GNU linkers. 161 162Internals 163--------- 164 165For the internals of the linker, please read :doc:`NewLLD`. It is a bit 166outdated but the fundamental concepts remain valid. We'll update the 167document soon. 168 169.. toctree:: 170 :maxdepth: 1 171 172 NewLLD 173 AtomLLD 174 WebAssembly 175 windows_support 176 missingkeyfunction 177 error_handling_script 178 Partitions 179 ReleaseNotes 180 ELF/linker_script 181 ELF/warn_backrefs 182