1Mach-O LLD Port
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. This document
7will describe the Mach-O port.
8
9Features
10--------
11
12- LLD is a drop-in replacement for Apple's Mach-O linker, ld64, that accepts the
13  same command line arguments.
14
15- LLD is very fast. When you link a large program on a multicore
16  machine, you can expect that LLD runs more than twice as fast as the ld64
17  linker.
18
19Download
20--------
21
22LLD is available as a pre-built binary by going to the `latest release <https://github.com/llvm/llvm-project/releases>`_,
23downloading the appropriate bundle (``clang+llvm-<version>-<your architecture>-<your platform>.tar.xz``),
24decompressing it, and locating the binary at ``bin/ld64.lld``. Note
25that if ``ld64.lld`` is moved out of ``bin``, it must still be accompanied
26by its sibling file ``lld``, as ``ld64.lld`` is technically a symlink to ``lld``.
27
28Build
29-----
30
31The easiest way to build LLD is to
32check out the entire LLVM projects/sub-projects from a git mirror and
33build that tree. You need ``cmake`` and of course a C++ compiler.
34
35.. code-block:: console
36
37  $ git clone https://github.com/llvm/llvm-project llvm-project
38  $ mkdir build
39  $ cd build
40  $ cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS='lld' ../llvm-project/llvm
41  $ ninja check-lld-macho
42
43Then you can find output binary at ``build/bin/ld64.lld``. Note
44that if ``ld64.lld`` is moved out of ``bin``, it must still be accompanied
45by its sibling file ``lld``, as ``ld64.lld`` is technically a symlink to ``lld``.
46
47Using LLD
48---------
49
50LLD can be used by adding ``-fuse-ld=/path/to/ld64.lld`` to the linker flags.
51For Xcode, this can be done by adding it to "Other linker flags" in the build
52settings. For Bazel, this can be done with ``--linkopt`` or with
53`rules_apple_linker <https://github.com/keith/rules_apple_linker>`_.
54
55.. seealso::
56
57  :doc:`ld64-vs-lld` has more info on the differences between the two linkers.
58
59.. toctree::
60   :hidden:
61
62   ld64-vs-lld
63