lld/docs/MachO/index.rst

   1 Mach-O LLD Port
   2 ===============
   3
   4 LLD is a linker from the LLVM project that is a drop-in replacement
   5 for system linkers and runs much faster than them. It also provides
   6 features that are useful for toolchain developers. This document
   7 will describe the Mach-O port.
   8
   9 Features
  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
  19 Download
  20 --------
  21
  22 LLD is available as a pre-built binary by going to the `latest release <https://github.com/llvm/llvm-project/releases>`_,
  23 downloading the appropriate bundle (``clang+llvm-<version>-<your architecture>-<your platform>.tar.xz``),
  24 decompressing it, and locating the binary at ``bin/ld64.lld``. Note
  25 that if ``ld64.lld`` is moved out of ``bin``, it must still be accompanied
  26 by its sibling file ``lld``, as ``ld64.lld`` is technically a symlink to ``lld``.
  27
  28 Build
  29 -----
  30
  31 The easiest way to build LLD is to
  32 check out the entire LLVM projects/sub-projects from a git mirror and
  33 build 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
  43 Then you can find output binary at ``build/bin/ld64.lld``. Note
  44 that if ``ld64.lld`` is moved out of ``bin``, it must still be accompanied
  45 by its sibling file ``lld``, as ``ld64.lld`` is technically a symlink to ``lld``.
  46
  47 Using LLD
  48 ---------
  49
  50 LLD can be used by adding ``-fuse-ld=/path/to/ld64.lld`` to the linker flags.
  51 For Xcode, this can be done by adding it to "Other linker flags" in the build
  52 settings. 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