[PATCH] D132893: Add docs for Mach-O lld

[Michael Eisel via Phabricator via llvm-commits]

michaeleisel created this revision.
Herald added subscribers: arphaman, dschuff.
Herald added a reviewer: MaskRay.
Herald added a reviewer: ributzka.
Herald added projects: lld-macho, All.
Herald added a reviewer: lld-macho.
michaeleisel requested review of this revision.
Herald added subscribers: llvm-commits, StephenFan, aheejin.
Herald added a project: LLVM.

Repository:
  rG LLVM Github Monorepo

https://reviews.llvm.org/D132893

Files:
  lld/docs/MachO/index.rst


Index: lld/docs/MachO/index.rst
===================================================================
--- /dev/null
+++ lld/docs/MachO/index.rst
@@ -0,0 +1,76 @@
+LLD - The LLVM Linker
+=====================
+
+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``.
+
+Build
+-----
+
+If you have already checked out LLVM using SVN, you can check out LLD
+under ``tools`` directory just like you probably did for clang. For the
+details, see `Getting Started with the LLVM System
+<https://llvm.org/docs/GettingStarted.html>`_.
+
+If you haven't checked out LLVM, 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 -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS=lld -DCMAKE_INSTALL_PREFIX=/usr/local ../llvm-project/llvm
+  $ make install
+
+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.
+
+Internals
+---------
+
+For the internals of the linker, please read :doc:`NewLLD`. It is a bit
+outdated but the fundamental concepts remain valid. We'll update the
+document soon.
+
+.. toctree::
+   :maxdepth: 1
+
+   NewLLD
+   WebAssembly
+   windows_support
+   missingkeyfunction
+   error_handling_script
+   Partitions
+   ReleaseNotes
+   ELF/linker_script
+   ELF/start-stop-gc
+   ELF/warn_backrefs


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D132893.456475.patch
Type: text/x-patch
Size: 2745 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20220829/086f5c10/attachment.bin>