[lld] 0f9590a - Add docs for Mach-O lld

Jez Ng via llvm-commits llvm-commits at lists.llvm.org
Tue Sep 6 09:24:45 PDT 2022


Author: Michael Eisel
Date: 2022-09-06T12:24:35-04:00
New Revision: 0f9590af273ffc6dea60e921c2454a4d2139bf1c

URL: https://github.com/llvm/llvm-project/commit/0f9590af273ffc6dea60e921c2454a4d2139bf1c
DIFF: https://github.com/llvm/llvm-project/commit/0f9590af273ffc6dea60e921c2454a4d2139bf1c.diff

LOG: Add docs for Mach-O lld

I wasn't able to find any docs for Mach-O in `lld/docs`, so here's an attempt at adding basic docs. One of my goals here is to make it easy for users who are unfamiliar with linkers to successfully use lld.

Reviewed By: #lld-macho, int3

Differential Revision: https://reviews.llvm.org/D132893

Added: 
    lld/docs/MachO/index.rst
    lld/docs/MachO/ld64-vs-lld.rst

Modified: 
    lld/docs/index.rst

Removed: 
    lld/MachO/ld64-vs-lld.rst


################################################################################
diff  --git a/lld/docs/MachO/index.rst b/lld/docs/MachO/index.rst
new file mode 100644
index 0000000000000..69583b24f3c94
--- /dev/null
+++ b/lld/docs/MachO/index.rst
@@ -0,0 +1,61 @@
+Mach-O LLD Port
+===============
+
+LLD is a linker from the LLVM project that is a drop-in replacement
+for system linkers and runs much faster than them. It also provides
+features that are useful for toolchain developers. This document
+will describe the Mach-O port.
+
+Features
+--------
+
+- LLD is a drop-in replacement for Apple's Mach-O linker, ld64, that accepts the
+  same command line arguments.
+
+- LLD is very fast. When you link a large program on a multicore
+  machine, you can expect that LLD runs more than twice as fast as the ld64 linker.
+
+Download
+--------
+
+LLD is available as a pre-built binary by going to the `latest release <https://github.com/llvm/llvm-project/releases>`_,
+downloading the appropriate bundle (``clang+llvm-<version>-<your architecture>-<your platform>.tar.xz``),
+decompressing it, and locating the binary at ``bin/ld64.lld``. Note
+that if ``ld64.lld`` is moved out of ``bin``, it must still be accompanied
+by its sibling file ``lld``, as ``ld64.lld`` is technically a symlink to ``lld``.
+
+Build
+-----
+
+The easiest way to build LLD is to
+check out the entire LLVM projects/sub-projects from a git mirror and
+build that tree. You need `cmake` and of course a C++ compiler.
+
+.. code-block:: console
+
+  $ git clone https://github.com/llvm/llvm-project llvm-project
+  $ mkdir build
+  $ cd build
+  $ cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS='lld' ../llvm-project/llvm
+  $ ninja check-lld-macho
+
+Then you can find output binary at ``build/bin/ld64.lld``. Note
+that if ``ld64.lld`` is moved out of ``bin``, it must still be accompanied
+by its sibling file ``lld``, as ``ld64.lld`` is technically a symlink to ``lld``.
+
+Using LLD
+---------
+
+LLD can be used by adding ``-fuse-ld=/path/to/ld64.lld`` to the linker flags.
+For Xcode, this can be done by adding it to "Other linker flags" in the build
+settings. For Bazel, this can be done with ``--linkopt`` or with
+[rules_apple_linker](https://github.com/keith/rules_apple_linker).
+The user may also need to add ``-Wl,--deduplicate-literals`` in order
+to match Apple's linker behavior more closely (otherwise problems
+can occur, for instance, in unit tests). For more info on
+the 
diff erences between the two, see "LD64 vs LLD-MACHO", mentioned below.
+
+.. toctree::
+   :maxdepth: 1
+
+   ld64-vs-lld

diff  --git a/lld/MachO/ld64-vs-lld.rst b/lld/docs/MachO/ld64-vs-lld.rst
similarity index 100%
rename from lld/MachO/ld64-vs-lld.rst
rename to lld/docs/MachO/ld64-vs-lld.rst

diff  --git a/lld/docs/index.rst b/lld/docs/index.rst
index 0086d7ec14f94..ce63203332437 100644
--- a/lld/docs/index.rst
+++ b/lld/docs/index.rst
@@ -168,3 +168,4 @@ document soon.
    ELF/linker_script
    ELF/start-stop-gc
    ELF/warn_backrefs
+   MachO/index


        


More information about the llvm-commits mailing list