151 lines · plain
1LLD - The LLVM Linker2=====================3 4LLD is a linker from the LLVM project that is a drop-in replacement5for system linkers and runs much faster than them. It also provides6features that are useful for toolchain developers.7 8The linker supports ELF (Unix), PE/COFF (Windows), Mach-O (macOS) and9WebAssembly in descending order of completeness. Internally, LLD consists of10several different linkers. The ELF port is the one that will be described in11this document. The PE/COFF port is complete, including12Windows debug info (PDB) support. The WebAssembly port is still a work in13progress (See :doc:`WebAssembly`).14 15Features16--------17 18- LLD is a drop-in replacement for the GNU linkers that accepts the19 same command line arguments and linker scripts as GNU.20 21- LLD is very fast. When you link a large program on a multicore22 machine, you can expect that LLD runs more than twice as fast as the GNU23 gold linker. Your mileage may vary, though.24 25- It supports various CPUs/ABIs including AArch64, AMDGPU, ARM, Hexagon,26 LoongArch, MIPS 32/64 big/little-endian, PowerPC, PowerPC64, RISC-V,27 SPARC V9, x86-32 and x86-64. Among these, AArch64, ARM (>= v4), LoongArch,28 PowerPC, PowerPC64, RISC-V, x86-32 and x86-64 have production quality.29 MIPS seems decent too.30 31- It is always a cross-linker, meaning that it always supports all the32 above targets however it was built. In fact, we don't provide a33 build-time option to enable/disable each target. This should make it34 easy to use our linker as part of a cross-compile toolchain.35 36- You can embed LLD in your program to eliminate dependencies on37 external linkers. All you have to do is to construct object files38 and command line arguments just like you would do to invoke an39 external linker and then call the linker's main function,40 ``lld::lldMain``, from your code.41 42- It is small. We are using LLVM libObject library to read from object43 files, so it is not a completely fair comparison, but as of February44 2017, LLD/ELF consists only of 21k lines of C++ code while GNU gold45 consists of 198k lines of C++ code.46 47- Link-time optimization (LTO) is supported by default. Essentially,48 all you have to do to do LTO is to pass the ``-flto`` option to clang.49 Then clang creates object files not in the native object file format50 but in LLVM bitcode format. LLD reads bitcode object files, compile51 them using LLVM and emit an output file. Because in this way LLD can52 see the entire program, it can do the whole program optimization.53 54- Some very old features for ancient Unix systems (pre-90s or even55 before that) have been removed. Some default settings have been56 tuned for the 21st century. For example, the stack is marked as57 non-executable by default to tighten security.58 59Performance60-----------61 62This is a link time comparison on a 2-socket 20-core 40-thread Xeon63E5-2680 2.80 GHz machine with an SSD drive. We ran gold and lld with64or without multi-threading support. To disable multi-threading, we65added ``-no-threads`` to the command lines.66 67============ =========== ============ ==================== ================== =============== =============68Program Output size GNU ld GNU gold w/o threads GNU gold w/threads lld w/o threads lld w/threads69ffmpeg dbg 92 MiB 1.72s 1.16s 1.01s 0.60s 0.35s70mysqld dbg 154 MiB 8.50s 2.96s 2.68s 1.06s 0.68s71clang dbg 1.67 GiB 104.03s 34.18s 23.49s 14.82s 5.28s72chromium dbg 1.14 GiB 209.05s [1]_ 64.70s 60.82s 27.60s 16.70s73============ =========== ============ ==================== ================== =============== =============74 75As you can see, lld is significantly faster than GNU linkers.76Note that this is just a benchmark result of our environment.77Depending on number of available cores, available amount of memory or78disk latency/throughput, your results may vary.79 80.. [1] Since GNU ld doesn't support the ``-icf=all`` and81 ``-gdb-index`` options, we removed them from the command line82 for GNU ld. GNU ld would have been slower than this if it had83 these options.84 85Build86-----87 88If you have already checked out LLVM using SVN, you can check out LLD89under ``tools`` directory just like you probably did for clang. For the90details, see `Getting Started with the LLVM System91<https://llvm.org/docs/GettingStarted.html>`_.92 93If you haven't checked out LLVM, the easiest way to build LLD is to94check out the entire LLVM projects/sub-projects from a git mirror and95build that tree. You need `cmake` and of course a C++ compiler.96 97.. code-block:: console98 99 $ git clone https://github.com/llvm/llvm-project llvm-project100 $ mkdir build101 $ cd build102 $ cmake -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS=lld -DCMAKE_INSTALL_PREFIX=/usr/local ../llvm-project/llvm103 $ make install104 105Using LLD106---------107 108LLD is installed as ``ld.lld``. On Unix, linkers are invoked by109compiler drivers, so you are not expected to use that command110directly. There are a few ways to tell compiler drivers to use ld.lld111instead of the default linker.112 113The easiest way to do that is to overwrite the default linker. After114installing LLD to somewhere on your disk, you can create a symbolic115link by doing ``ln -s /path/to/ld.lld /usr/bin/ld`` so that116``/usr/bin/ld`` is resolved to LLD.117 118If you don't want to change the system setting, you can use clang's119``-fuse-ld`` option. In this way, you want to set ``-fuse-ld=lld`` to120LDFLAGS when building your programs.121 122LLD leaves its name and version number to a ``.comment`` section in an123output. If you are in doubt whether you are successfully using LLD or124not, run ``readelf --string-dump .comment <output-file>`` and examine the125output. If the string "Linker: LLD" is included in the output, you are126using LLD.127 128Internals129---------130 131For the internals of the linker, please read :doc:`NewLLD`. It is a bit132outdated but the fundamental concepts remain valid. We'll update the133document soon.134 135.. toctree::136 :maxdepth: 1137 138 NewLLD139 WebAssembly140 windows_support141 missingkeyfunction142 error_handling_script143 Partitions144 ReleaseNotes145 ELF/large_sections146 ELF/linker_script147 ELF/start-stop-gc148 ELF/warn_backrefs149 MachO/index150 DTLTO151