<div dir="ltr">Thank you so much for doing this. A couple comments inline:<br><div class="gmail_extra"><br><div class="gmail_quote">On Thu, Feb 23, 2017 at 5:55 PM, Rui Ueyama via llvm-commits <span dir="ltr"><<a href="mailto:llvm-commits@lists.llvm.org" target="_blank">llvm-commits@lists.llvm.org</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Author: ruiu<br>
Date: Thu Feb 23 19:55:50 2017<br>
New Revision: 296072<br>
<br>
URL: <a href="http://llvm.org/viewvc/llvm-project?rev=296072&view=rev" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-<wbr>project?rev=296072&view=rev</a><br>
Log:<br>
Update the main document of LLD for those who are not familiar with the project.<br>
<br>
Modified:<br>
lld/trunk/docs/index.rst<br>
<br>
Modified: lld/trunk/docs/index.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/lld/trunk/docs/index.rst?rev=296072&r1=296071&r2=296072&view=diff" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-<wbr>project/lld/trunk/docs/index.<wbr>rst?rev=296072&r1=296071&r2=<wbr>296072&view=diff</a><br>
==============================<wbr>==============================<wbr>==================<br>
--- lld/trunk/docs/index.rst (original)<br>
+++ lld/trunk/docs/index.rst Thu Feb 23 19:55:50 2017<br>
@@ -1,25 +1,137 @@<br>
-.. _index:<br>
-<br>
-lld - The LLVM Linker<br>
+LLD - The LLVM Linker<br>
=====================<br>
<br>
-lld contains two linkers whose architectures are different from each other.<br>
-<br>
-.. toctree::<br>
- :maxdepth: 1<br>
-<br>
- NewLLD<br>
- AtomLLD<br>
-<br>
-Source<br>
-------<br>
-<br>
-lld is available in the LLVM SVN repository::<br>
-<br>
- svn co <a href="http://llvm.org/svn/llvm-project/lld/trunk" rel="noreferrer" target="_blank">http://llvm.org/svn/llvm-<wbr>project/lld/trunk</a> lld<br>
-<br>
-lld is also available via the read-only git mirror::<br>
-<br>
- git clone <a href="http://llvm.org/git/lld.git" rel="noreferrer" target="_blank">http://llvm.org/git/lld.git</a><br>
-<br>
-Put it in llvm's tools/ directory, rerun cmake, then build target lld.<br>
+LLD is a linker from the LLVM project. That is a drop-in replacement<br>
+for system linkers and runs much faster than them. It also provides<br>
+features that are useful for toolchain developers.<br>
+<br>
+The linker supports ELF (Unix), PE/COFF (Windows) and Mach-O (macOS)<br>
+in descending order of completeness. Internally, LLD consists of three<br>
+different linkers. The ELF port is the one that will be described in<br>
+this document. The PE/COFF port is almost complete except the lack of<br>
+the Windows debug info (PDB) support. The Mach-O port is built based<br>
+on a different architecture than the ELF or COFF ports. For the<br>
+details about Mach-O, please read AtomLLD_.<br>
+<br>
+Features<br>
+--------<br>
+<br>
+- LLD is a drop-in replacement for the GNU linkers. That accepts the<br>
+ same command line arguments and linker scripts as GNU. Although our<br>
+ linker is relatively new and still in active development, that is<br>
+ already able to link the entire FreeBSD/amd64 base system including<br>
+ the kernel.</blockquote><div><br></div><div>Mention the ports as well?</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"> We are currently working closely with the FreeBSD<br>
+ project to make LLD default system linker in future versions of the<br>
+ operating system, so we are serious about addressing compatibility<br>
+ issues.<br>
+<br>
+- LLD is very fast. When you link a large program on a multicore<br>
+ machine, you can expect that LLD runs more than twice as fast as GNU<br>
+ gold linker. Your milage may vary, though.<br>
+<br>
+- It supports various CPUs/ABIs including x86-64, x86, x32, AArch64,<br>
+ ARM, MIPS 32/64 big/little-endian, PowerPC, PowerPC 64 and AMDGPU.<br>
+ Among these, x86-64 is the most well-supported target and have<br>
+ reached production quality. AArch64 and MIPS seem decent too. x86<br>
+ should be OK but not well tested yet. ARM support is being developed<br>
+ actively.<br>
+<br>
+- It is always a cross-linker, meaning that it always supports all the<br>
+ above targets however it was built. In fact, we don't provide a<br>
+ build-time option to enable/disable each target. This should make it<br>
+ easy to use our linker as part of a cross-compile toolchain.<br>
+<br>
+- You can embed LLD to your program to eliminate dependency to<br>
+ external linkers. All you have to do is to construct object files<br>
+ and command line arguments just like you would do to invoke an<br>
+ external linker and then call the linker's main function,<br>
+ `lld::elf::link`, from your code.<br>
+<br>
+- It is small. We are using LLVM libObject library to read from object<br>
+ files, so it is not completely a fair comparison, but as of February<br>
+ 2017, LLD/ELF consists only of 21k lines of C++ code while GNU gold<br>
+ consists of 198k lines of C++ code.<br>
+<br>
+- Link-time optimization (LTO) is supported by default. Essentially,<br>
+ all you have to do to do LTO is to pass the `-flto` option to clang.<br>
+ Then clang creates object files not in the native object file format<br>
+ but in LLVM bitcode format. LLD reads bitcode object files, compile<br>
+ them using LLVM and emit an output file. Because in this way LLD can<br>
+ see the entire program, it can do the whole program optimization.<br>
+<br>
+- Some very old features for ancient Unix systems (pre-90s or even<br>
+ before that) have been removed. Some default settings have been<br>
+ tuned for the 21st century. For example, the stack is marked as<br>
+ non-executable by default to tighten security.<br>
+<br>
+Performance<br>
+-----------<br>
+<br>
+This is a link time comparison on a 2-socket 20-core 40-thread Xeon<br>
+E5-2680 2.80 GHz machine with an SSD drive.<br>
+<br>
+LLD is much faster than the GNU linkers for large programs. That's<br>
+fast for small programs too, but because the link time is short<br>
+anyway, the difference is not very noticeable in that case.<br>
+<br>
+Note that this is just a benchmark result of our environment.<br>
+Depending on number of available cores, available amount of memory or<br>
+disk latency/throughput, your results may vary.<br>
+<br>
+============ =========== ====== ======== ======<br>
+Program Output size GNU ld GNU gold LLD<br>
+ffmpeg dbg 92 MiB 1.59s 1.15s 0.78s<br>
+mysqld dbg 158 MiB 7.09s 2.49s 1.31s<br>
+clang dbg 1.55 GiB 86.76s 21.93s 8.38s<br>
+chromium dbg 1.57 GiB N/A 40.86s 12.69s<br>
+============ =========== ====== ======== ======<br>
+<br>
+Build<br>
+-----<br>
+<br>
+If you have already checked out LLVM using SVN, you can check out LLD<br>
+under `tools` directory just like you probably did for clang. For the<br>
+details, see `Getting Started with the LLVM System<br>
+<<a href="http://llvm.org/docs/GettingStarted.html" rel="noreferrer" target="_blank">http://llvm.org/docs/<wbr>GettingStarted.html</a>>`_.<br>
+<br>
+If you haven't checkout out LLVM, the easiest way to build LLD is to<br>
+checkout the entire LLVM projects/sub-projects from a git mirror and<br>
+build that tree. You need `cmake` and of course a C++ compiler.<br>
+<br>
+.. code-block:: console<br>
+<br>
+ $ git clone <a href="https://github.com/llvm-project/llvm-project/" rel="noreferrer" target="_blank">https://github.com/llvm-<wbr>project/llvm-project/</a><br>
+ $ mkdir build<br>
+ $ cd build<br>
+ $ cmake -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS=lld -DCMAKE_INSTALL_PREFIX=/usr/<wbr>local ../llvm-project/llvm<br>
+ $ make install<br>
+<br>
+History<br>
+-------<br>
+<br>
+Here is a brief project history of the ELF and COFF ports.<br>
+<br>
+- May 2015: We decided to rewrite the COFF linker and did that.<br>
+ Noticed that the new linker is much faster than the MSVC linker.<br>
+<br>
+- July 2015: The new ELF port was developed based on the COFF linker<br>
+ architecture.<br>
+<br>
+- September 2015: The first patches to support MIPS and AArch64 landed.<br>
+<br>
+- October 2015: Succeeded to self-host the ELF port. We have noticed<br>
+ that the linker was faster than the GNU linkers, but we weren't sure<br>
+ at the time if we would be able to keep the gap as we would add more<br>
+ features to the linker.<br>
+<br>
+- July 2016: Started working on improving the linker script support.<br>
+<br>
+- December 2016: Succeeded to build the entire FreeBSD base system<br>
+ including the kernel. We had widen the gap against the GNU linkers.<br></blockquote><div><br></div><div>s/gap/performance gap/ for clarity?</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
+<br>
+Internals<br>
+---------<br>
+<br>
+For the internals of the linker, please read NewLLD_. It is a bit<br>
+outdated but the fundamental concepts remain valid. We'll update the<br>
+document soon.<br>
<br>
<br>
______________________________<wbr>_________________<br>
llvm-commits mailing list<br>
<a href="mailto:llvm-commits@lists.llvm.org">llvm-commits@lists.llvm.org</a><br>
<a href="http://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-commits" rel="noreferrer" target="_blank">http://lists.llvm.org/cgi-bin/<wbr>mailman/listinfo/llvm-commits</a><br>
</blockquote></div><br></div></div>