Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
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
- Loading branch information
1 parent
ae117e1
commit 0f9590a
Showing
3 changed files
with
62 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 differences between the two, see "LD64 vs LLD-MACHO", mentioned below. | ||
|
||
.. toctree:: | ||
:maxdepth: 1 | ||
|
||
ld64-vs-lld |
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -168,3 +168,4 @@ document soon. | |
ELF/linker_script | ||
ELF/start-stop-gc | ||
ELF/warn_backrefs | ||
MachO/index |