diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Driver.rst | 2 | ||||
| -rw-r--r-- | docs/NewLLD.rst | 139 | ||||
| -rw-r--r-- | docs/ReleaseNotes.rst | 169 | ||||
| -rw-r--r-- | docs/WebAssembly.rst | 36 | ||||
| -rw-r--r-- | docs/_templates/indexsidebar.html | 2 | ||||
| -rw-r--r-- | docs/conf.py | 4 | ||||
| -rw-r--r-- | docs/index.rst | 55 | ||||
| -rw-r--r-- | docs/sphinx_intro.rst | 36 |
8 files changed, 159 insertions, 284 deletions
diff --git a/docs/Driver.rst b/docs/Driver.rst index 27b378712a6c..4ee6ce0c985f 100644 --- a/docs/Driver.rst +++ b/docs/Driver.rst @@ -65,7 +65,7 @@ Adding an Option to an existing Flavor Adding a Flavor =============== -#. Add an entry for the flavor in :file:`include/lld/Driver/Driver.h` to +#. Add an entry for the flavor in :file:`include/lld/Common/Driver.h` to :cpp:class:`lld::UniversalDriver::Flavor`. #. Add an entry in :file:`lib/Driver/UniversalDriver.cpp` to diff --git a/docs/NewLLD.rst b/docs/NewLLD.rst index 67f6b368b0e4..afdb41e0a145 100644 --- a/docs/NewLLD.rst +++ b/docs/NewLLD.rst @@ -1,5 +1,5 @@ -The ELF and COFF Linkers -======================== +The ELF, COFF and Wasm Linkers +============================== The ELF Linker as a Library --------------------------- @@ -33,11 +33,12 @@ between speed, simplicity and extensibility. We implemented the linkers as native linkers for each file format. - The two linkers share the same design but do not share code. + The linkers share the same design but share very little code. Sharing code makes sense if the benefit is worth its cost. - In our case, ELF and COFF are different enough that we thought the layer to - abstract the differences wouldn't worth its complexity and run-time cost. - Elimination of the abstract layer has greatly simplified the implementation. + In our case, the object formats are different enough that we thought the layer + to abstract the differences wouldn't be worth its complexity and run-time + cost. Elimination of the abstract layer has greatly simplified the + implementation. * Speed by design @@ -57,59 +58,61 @@ between speed, simplicity and extensibility. * Efficient archive file handling - LLD's handling of archive files (the files with ".a" file extension) is different - from the traditional Unix linkers and similar to Windows linkers. - We'll describe how the traditional Unix linker handles archive files, - what the problem is, and how LLD approached the problem. + LLD's handling of archive files (the files with ".a" file extension) is + different from the traditional Unix linkers and similar to Windows linkers. + We'll describe how the traditional Unix linker handles archive files, what the + problem is, and how LLD approached the problem. - The traditional Unix linker maintains a set of undefined symbols during linking. - The linker visits each file in the order as they appeared in the command line - until the set becomes empty. What the linker would do depends on file type. + The traditional Unix linker maintains a set of undefined symbols during + linking. The linker visits each file in the order as they appeared in the + command line until the set becomes empty. What the linker would do depends on + file type. - - If the linker visits an object file, the linker links object files to the result, - and undefined symbols in the object file are added to the set. + - If the linker visits an object file, the linker links object files to the + result, and undefined symbols in the object file are added to the set. - - If the linker visits an archive file, it checks for the archive file's symbol table - and extracts all object files that have definitions for any symbols in the set. + - If the linker visits an archive file, it checks for the archive file's + symbol table and extracts all object files that have definitions for any + symbols in the set. - This algorithm sometimes leads to a counter-intuitive behavior. - If you give archive files before object files, nothing will happen - because when the linker visits archives, there is no undefined symbols in the set. - As a result, no files are extracted from the first archive file, - and the link is done at that point because the set is empty after it visits one file. + This algorithm sometimes leads to a counter-intuitive behavior. If you give + archive files before object files, nothing will happen because when the linker + visits archives, there is no undefined symbols in the set. As a result, no + files are extracted from the first archive file, and the link is done at that + point because the set is empty after it visits one file. You can fix the problem by reordering the files, but that cannot fix the issue of mutually-dependent archive files. - Linking mutually-dependent archive files is tricky. - You may specify the same archive file multiple times to - let the linker visit it more than once. - Or, you may use the special command line options, `--start-group` and `--end-group`, - to let the linker loop over the files between the options until + Linking mutually-dependent archive files is tricky. You may specify the same + archive file multiple times to let the linker visit it more than once. Or, + you may use the special command line options, `--start-group` and + `--end-group`, to let the linker loop over the files between the options until no new symbols are added to the set. Visiting the same archive files multiple makes the linker slower. - Here is how LLD approaches the problem. Instead of memorizing only undefined symbols, - we program LLD so that it memorizes all symbols. - When it sees an undefined symbol that can be resolved by extracting an object file - from an archive file it previously visited, it immediately extracts the file and link it. - It is doable because LLD does not forget symbols it have seen in archive files. + Here is how LLD approaches the problem. Instead of memorizing only undefined + symbols, we program LLD so that it memorizes all symbols. When it sees an + undefined symbol that can be resolved by extracting an object file from an + archive file it previously visited, it immediately extracts the file and link + it. It is doable because LLD does not forget symbols it have seen in archive + files. We believe that the LLD's way is efficient and easy to justify. - The semantics of LLD's archive handling is different from the traditional Unix's. - You can observe it if you carefully craft archive files to exploit it. - However, in reality, we don't know any program that cannot link - with our algorithm so far, so it's not going to cause trouble. + The semantics of LLD's archive handling is different from the traditional + Unix's. You can observe it if you carefully craft archive files to exploit + it. However, in reality, we don't know any program that cannot link with our + algorithm so far, so it's not going to cause trouble. Numbers You Want to Know ------------------------ To give you intuition about what kinds of data the linker is mainly working on, I'll give you the list of objects and their numbers LLD has to read and process -in order to link a very large executable. In order to link Chrome with debug info, -which is roughly 2 GB in output size, LLD reads +in order to link a very large executable. In order to link Chrome with debug +info, which is roughly 2 GB in output size, LLD reads - 17,000 files, - 1,800,000 sections, @@ -136,17 +139,17 @@ when handling files. Important Data Structures ------------------------- -We will describe the key data structures in LLD in this section. -The linker can be understood as the interactions between them. -Once you understand their functions, the code of the linker should look obvious to you. +We will describe the key data structures in LLD in this section. The linker can +be understood as the interactions between them. Once you understand their +functions, the code of the linker should look obvious to you. -* SymbolBody +* Symbol - SymbolBody is a class to represent symbols. + This class represents a symbol. They are created for symbols in object files or archive files. The linker creates linker-defined symbols as well. - There are basically three types of SymbolBodies: Defined, Undefined, or Lazy. + There are basically three types of Symbols: Defined, Undefined, or Lazy. - Defined symbols are for all symbols that are considered as "resolved", including real defined symbols, COMDAT symbols, common symbols, @@ -156,33 +159,25 @@ Once you understand their functions, the code of the linker should look obvious - Lazy symbols represent symbols we found in archive file headers which can turn into Defined if we read archieve members. -* Symbol + There's only one Symbol instance for each unique symbol name. This uniqueness + is guaranteed by the symbol table. As the resolver reads symbols from input + files, it replaces an existing Symbol with the "best" Symbol for its symbol + name using the placement new. - A Symbol is a container for a SymbolBody. There's only one Symbol for each - unique symbol name (this uniqueness is guaranteed by the symbol table). - Each global symbol has only one SymbolBody at any one time, which is - the SymbolBody stored within a memory region of the Symbol large enough - to store any SymbolBody. - - As the resolver reads symbols from input files, it replaces the Symbol's - SymbolBody with the "best" SymbolBody for its symbol name by constructing - the new SymbolBody in place on top of the existing SymbolBody. For example, - if the resolver is given a defined symbol, and the SymbolBody with its name - is undefined, it will construct a Defined SymbolBody over the Undefined - SymbolBody. - - This means that each SymbolBody pointer always points to the best SymbolBody, - and it is possible to get from a SymbolBody to a Symbol, or vice versa, - by adding or subtracting a fixed offset. This memory layout helps reduce - the cache miss rate through high locality and a small number of required - pointer indirections. + The above mechanism allows you to use pointers to Symbols as a very cheap way + to access name resolution results. Assume for example that you have a pointer + to an undefined symbol before name resolution. If the symbol is resolved to a + defined symbol by the resolver, the pointer will "automatically" point to the + defined symbol, because the undefined symbol the pointer pointed to will have + been replaced by the defined symbol in-place. * SymbolTable SymbolTable is basically a hash table from strings to Symbols with logic to resolve symbol conflicts. It resolves conflicts by symbol type. - - If we add Defined and Undefined symbols, the symbol table will keep the former. + - If we add Defined and Undefined symbols, the symbol table will keep the + former. - If we add Defined and Lazy symbols, it will keep the former. - If we add Lazy and Undefined, it will keep the former, but it will also trigger the Lazy symbol to load the archive member @@ -221,15 +216,14 @@ There are mainly three actors in this linker. InputFile is a superclass of file readers. We have a different subclass for each input file type, such as regular object file, archive file, etc. - They are responsible for creating and owning SymbolBodies and - InputSections/Chunks. + They are responsible for creating and owning Symbols and InputSections/Chunks. * Writer - The writer is responsible for writing file headers and InputSections/Chunks to a file. - It creates OutputSections, put all InputSections/Chunks into them, - assign unique, non-overlapping addresses and file offsets to them, - and then write them down to a file. + The writer is responsible for writing file headers and InputSections/Chunks to + a file. It creates OutputSections, put all InputSections/Chunks into them, + assign unique, non-overlapping addresses and file offsets to them, and then + write them down to a file. * Driver @@ -237,7 +231,8 @@ There are mainly three actors in this linker. - processes command line options, - creates a symbol table, - - creates an InputFile for each input file and puts all symbols within into the symbol table, + - creates an InputFile for each input file and puts all symbols within into + the symbol table, - checks if there's no remaining undefined symbols, - creates a writer, - and passes the symbol table to the writer to write the result to a file. @@ -301,7 +296,7 @@ Glossary they are merged by ICF. It is known as an effective technique, and it usually reduces C++ program's size by a few percent or more. - Note that this is not entirely sound optimization. C/C++ require + Note that this is not an entirely sound optimization. C/C++ require different functions have different addresses. If a program depends on that property, it would fail at runtime. diff --git a/docs/ReleaseNotes.rst b/docs/ReleaseNotes.rst index 01a984148b7e..dcd6ac0602d3 100644 --- a/docs/ReleaseNotes.rst +++ b/docs/ReleaseNotes.rst @@ -1,23 +1,22 @@ ======================= -lld 5.0.0 Release Notes +LLD 6.0.0 Release Notes ======================= .. contents:: :local: +.. warning:: + These are in-progress notes for the upcoming LLVM 6.0.0 release. + Release notes for previous releases can be found on + `the Download Page <http://releases.llvm.org/download.html>`_. + Introduction ============ -lld is a linker from the LLVM project. It supports ELF (Unix), COFF (Windows) -and Mach-O (macOS), and it is generally faster than the GNU bfd or gold linkers -or the MSVC linker. - -lld is designed to be a drop-in replacement for the system linkers, so that -users don't need to change their build systems other than swapping the linker -command. - -All lld releases may be downloaded from the `LLVM releases web site -<http://llvm.org/releases/>`_. +This document contains the release notes for the LLD linker, release 6.0.0. +Here we describe the status of LLD, including major improvements +from the previous release. All LLD releases may be downloaded +from the `LLVM releases web site <http://llvm.org/releases/>`_. Non-comprehensive list of changes in this release ================================================= @@ -25,148 +24,14 @@ Non-comprehensive list of changes in this release ELF Improvements ---------------- -* First and foremost, a lot of compatibility issues and bugs have been fixed. - Linker script support has significantly improved. As a result, we believe you - are very likely to be able to link your programs with lld without experiencing - any problem now. - -* Error message format has changed in order to improve readability. - Traditionally, linker's error messages are concise and arguably too terse. - This is an example of lld 4.0.0's error message (they are actually in one line):: - - /ssd/clang/bin/ld.lld: error: /ssd/llvm-project/lld/ELF/Writer.cpp:207: - undefined symbol 'lld::elf::EhFrameSection::addSection()' - - It is not easy to read because too much information is packed into a single line - and the embedded text, particularly a symbol name, is sometimes too long. - In lld 5.0.0, we use more vertical space to print out error messages in a more - structured manner like this:: - - bin/ld.lld: error: undefined symbol: lld::elf::EhFrameSection::addSection() - >>> Referenced by Writer.cpp:207 (/ssd/llvm-project/lld/ELF/Writer.cpp:207) - >>> Writer.cpp.o in archive lib/liblldELF.a - - As a bonus, the new error message contains source code location of the error - if it is available from debug info. - -* ``./configure`` scripts generated by GNU autoconf determines whether a linker - supports modern GNU-compatible features or not by searching for "GNU" in the - ``--help`` message. To be compatible with the scripts, we decided to add a - string "(compatible with GNU linkers)" to our ``--help`` message. This is a - hack, but just like the web browser's User-Agent string (which everyone still - claim they are "Mozilla/5.0"), we had no choice other than doing this to claim - that we accept GNU-compatible options. +* Item 1. -* The ``-Map`` option is added. The option is to make the linker to print out how - input files are mapped to the output file. Here is an example:: +COFF Improvements +----------------- - Address Size Align Out In Symbol - 00000000016d84d8 00000000008f8f50 8 .eh_frame - 00000000016d84d8 00000000008f8f50 8 <internal>:(.eh_frame) - 0000000001fd2000 00000000034b3bd0 16 .text - 0000000001fd2000 000000000000002a 1 /usr/lib/x86_64-linux-gnu/crt1.o:(.text) - 0000000001fd2000 0000000000000000 0 _start - 0000000001fd202a 0000000000000000 1 /usr/lib/x86_64-linux-gnu/crti.o:(.text) - 0000000001fd2030 00000000000000bd 16 /usr/lib/gcc/x86_64-linux-gnu/4.8/crtbegin.o:(.text) - 0000000001fd2030 0000000000000000 0 deregister_tm_clones - 0000000001fd2060 0000000000000000 0 register_tm_clones - - This format is not the same as GNU linkers as our linker internal data - structure is different from them but contains the same amount of information - and should be more readable than their outputs. - - As with other lld features, the ``-Map`` option is designed with speed in mind. - The option would generate a hundred megabyte text file if you link a large - program with it. lld can usually do that in a few seconds, and it is generally - a few times faster than the GNU gold's ``-Map`` option. - -* lld's ``--gdb-index`` option used to be slow, but we sped it up so that it is - at least as fast as the GNU gold. - -* Some nonstandard relocations, such as R_X86_64_8 or R_X86_64_16, are supported. - They are not used for 32/64-bit applications, but some 16-bit bootloaders need - them. - -* Paddings in executable text sections are now filled with trap instructions - (such as INT3) instead of being left as null bytes. This change improves - disassembler outputs because it now prints out trap instructions instead of - trying to decode 0x00 as an instruction. It also makes debugging of some type - of program easier because when the control reaches a padding, the program - immediately raises an error. - -* The following options are added: ``-M``, ``-Map``, - ``-compress-debug-sections``, ``-emit-relocs``, - ``-error-unresolved-symbols``, ``-exclude-libs``, ``-filter``, - ``-no-dynamic-linker``, ``-no-export-dynamic``, ``-no-fatal-warnings``, - ``-print-map``, ``-warn-unresolved-symbols``, ``-z nocopyreloc``, - ``-z notext``, ``-z rodynamic`` - - -Contributors to lld 5.0 -======================= +* Item 1. -We had 63 individuals contribute to lld 5.0. Thank you so much! +MachO Improvements +------------------ -- Adrian McCarthy -- Alberto Magni -- Alexander Richardson -- Andre Vieira -- Andrew Ng -- Anton Korobeynikov -- Bob Haarman -- David Blaikie -- Davide Italiano -- David L. Jones -- Dmitry Mikulin -- Ed Maste -- Ed Schouten -- Eric Beckmann -- Eric Fiselier -- Eugene Leviant -- Evgeniy Stepanov -- Galina Kistanova -- George Rimar -- Hans Wennborg -- Igor Kudrin -- Ismail Donmez -- Jake Ehrlich -- James Henderson -- Joel Jones -- Jon Chesterfield -- Kamil Rytarowski -- Kevin Enderby -- Konstantin Zhuravlyov -- Kyungwoo Lee -- Leslie Zhai -- Mark Kettenis -- Martell Malone -- Martin Storsjo -- Meador Inge -- Mehdi Amini -- Michal Gorny -- NAKAMURA Takumi -- Paul Robinson -- Pavel Labath -- Petar Jovanovic -- Peter Collingbourne -- Peter Smith -- Petr Hosek -- Rafael Espindola -- Reid Kleckner -- Richard Smith -- Robert Clarke -- Rui Ueyama -- Saleem Abdulrasool -- Sam Clegg -- Sean Eveson -- Sean Silva -- Shankar Easwaran -- Shoaib Meenai -- Simon Atanasyan -- Simon Dardis -- Simon Tatham -- Sylvestre Ledru -- Tom Stellard -- Vitaly Buka -- Yuka Takahashi -- Zachary Turner +* Item 1. diff --git a/docs/WebAssembly.rst b/docs/WebAssembly.rst new file mode 100644 index 000000000000..1df8fa3a82b0 --- /dev/null +++ b/docs/WebAssembly.rst @@ -0,0 +1,36 @@ +WebAssembly lld port +==================== + +Note: The WebAssembly port is still a work in progress and is be lacking +certain features. + +The WebAssembly version of lld takes WebAssembly binaries as inputs and produces +a WebAssembly binary as its output. For the most part this port tried to mimic +the behaviour of traditional ELF linkers and specifically the ELF lld port. +Where possible that command line flags and the semantics should be the same. + + +Object file format +------------------ + +The format the input object files that lld expects is specified as part of the +the WebAssembly tool conventions +https://github.com/WebAssembly/tool-conventions/blob/master/Linking.md. + +This is object format that the llvm will produce when run with the +``wasm32-unknown-unknown-wasm`` target. To build llvm with WebAssembly support +currently requires enabling the experimental backed using +``-DLLVM_EXPERIMENTAL_TARGETS_TO_BUILD=WebAssembly``. + + +Missing features +---------------- + +There are several key features that are not yet implement in the WebAssembly +ports: + +- COMDAT support. This means that support for C++ is still very limited. +- Function stripping. Currently there is no support for ``--gc-sections`` so + functions and data from a given object will linked as a unit. +- Section start/end symbols. The synthetic symbols that mark the start and + of data regions are not yet created in the output file. diff --git a/docs/_templates/indexsidebar.html b/docs/_templates/indexsidebar.html index 61968f22d5c5..588be9309bde 100644 --- a/docs/_templates/indexsidebar.html +++ b/docs/_templates/indexsidebar.html @@ -1,4 +1,4 @@ <h3>Bugs</h3> <p>lld bugs should be reported at the - LLVM <a href="http://llvm.org/bugs">Bugzilla</a>.</p> + LLVM <a href="https://bugs.llvm.org/">Bugzilla</a>.</p> diff --git a/docs/conf.py b/docs/conf.py index 410b33e98ace..28e16f5b8856 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -48,9 +48,9 @@ copyright = u'2011-%d, LLVM Project' % date.today().year # built documents. # # The short version. -version = '5' +version = '6' # The full version, including alpha/beta/rc tags. -release = '5' +release = '6' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/docs/index.rst b/docs/index.rst index fbdade7daf27..f4bf3be9bf29 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -5,13 +5,14 @@ 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. -The linker supports ELF (Unix), PE/COFF (Windows) and Mach-O (macOS) -in descending order of completeness. Internally, LLD consists of three -different linkers. The ELF port is the one that will be described in -this document. The PE/COFF port is almost complete except the lack of -the Windows debug info (PDB) support. The Mach-O port is built based -on a different architecture than the ELF or COFF ports. For the -details about Mach-O, please read :doc:`AtomLLD`. +The linker supports ELF (Unix), PE/COFF (Windows), Mach-O (macOS) and +WebAssembly in descending order of completeness. Internally, LLD consists of +several different linkers. The ELF port is the one that will be described in +this document. The PE/COFF port is almost complete except the lack of the +Windows debug info (PDB) support. The WebAssembly port is still a work in +progress (See :doc:`WebAssembly`). The Mach-O port is built based on a +different architecture than the others. For the details about Mach-O, please +read :doc:`AtomLLD`. Features -------- @@ -71,30 +72,27 @@ Performance ----------- This is a link time comparison on a 2-socket 20-core 40-thread Xeon -E5-2680 2.80 GHz machine with an SSD drive. - -LLD is much faster than the GNU linkers for large programs. That's -fast for small programs too, but because the link time is short -anyway, the difference is not very noticeable in that case. - +E5-2680 2.80 GHz machine with an SSD drive. We ran gold and lld with +or without multi-threading support. To disable multi-threading, we +added ``-no-threads`` to the command lines. + +============ =========== ============ ==================== ================== =============== ============= +Program Output size GNU ld GNU gold w/o threads GNU gold w/threads lld w/o threads lld w/threads +ffmpeg dbg 92 MiB 1.72s 1.16s 1.01s 0.60s 0.35s +mysqld dbg 154 MiB 8.50s 2.96s 2.68s 1.06s 0.68s +clang dbg 1.67 GiB 104.03s 34.18s 23.49s 14.82s 5.28s +chromium dbg 1.14 GiB 209.05s [1]_ 64.70s 60.82s 27.60s 16.70s +============ =========== ============ ==================== ================== =============== ============= + +As you can see, lld is significantly faster than GNU linkers. Note that this is just a benchmark result of our environment. Depending on number of available cores, available amount of memory or disk latency/throughput, your results may vary. -============ =========== ============ ============= ====== -Program Output size GNU ld GNU gold [1]_ LLD -ffmpeg dbg 91 MiB 1.59s 1.15s 0.78s -mysqld dbg 157 MiB 7.09s 2.49s 1.31s -clang dbg 1.45 GiB 86.76s 21.93s 8.38s -chromium dbg 1.52 GiB 142.30s [2]_ 40.86s 12.69s -============ =========== ============ ============= ====== - -.. [1] With the ``--threads`` option to enable multi-threading support. - -.. [2] Since GNU ld doesn't support the ``-icf=all`` option, we - removed that from the command line for GNU ld. GNU ld would be - slower than this if it had that option support. For gold and - LLD, we use ``-icf=all``. +.. [1] Since GNU ld doesn't support the ``-icf=all`` and + ``-gdb-index`` options, we removed them from the command line + for GNU ld. GNU ld would have been slower than this if it had + these options. Build ----- @@ -110,7 +108,7 @@ build that tree. You need `cmake` and of course a C++ compiler. .. code-block:: console - $ git clone https://github.com/llvm-project/llvm-project/ + $ git clone https://github.com/llvm-project/llvm-project-20170507 llvm-project $ mkdir build $ cd build $ cmake -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS=lld -DCMAKE_INSTALL_PREFIX=/usr/local ../llvm-project/llvm @@ -175,5 +173,6 @@ document soon. NewLLD AtomLLD + WebAssembly windows_support ReleaseNotes diff --git a/docs/sphinx_intro.rst b/docs/sphinx_intro.rst index 6845bc812e78..6bb9816b5ab4 100644 --- a/docs/sphinx_intro.rst +++ b/docs/sphinx_intro.rst @@ -57,41 +57,21 @@ to install it using: Building the documentation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -In order to build the documentation, all you should need to do is change to the -``docs`` directory and invoke make as follows:: - - $ cd path/to/project/docs - $ make html - -Note that on Windows there is a ``make.bat`` command in the docs directory which -supplies the same interface as the ``Makefile``. - -That command will invoke ``sphinx-build`` with the appropriate options for the -project, and generate the HTML documentation in a ``_build`` subdirectory. You -can browse it starting from the index page by visiting -``_build/html/index.html``. - -Sphinx supports a wide variety of generation formats (including LaTeX, man -pages, and plain text). The ``Makefile`` includes a number of convenience -targets for invoking ``sphinx-build`` appropriately, the common ones are: - - make html - Generate the HTML output. - - make latexpdf - Generate LaTeX documentation and convert to a PDF. - - make man - Generate man pages. +In order to build the documentation need to add ``-DLLVM_ENABLE_SPHINX=ON`` to +your ``cmake`` command. Once you do this you can build the docs using +``docs-lld-html`` build (``ninja`` or ``make``) target. +That build target will invoke ``sphinx-build`` with the appropriate options for +the project, and generate the HTML documentation in a ``tools/lld/docs/html`` +subdirectory. .. _writing_documentation: Writing documentation ~~~~~~~~~~~~~~~~~~~~~ -The documentation itself is written in the reStructuredText (ReST) format, and Sphinx -defines additional tags to support features like cross-referencing. +The documentation itself is written in the reStructuredText (ReST) format, and +Sphinx defines additional tags to support features like cross-referencing. The ReST format itself is organized around documents mostly being readable plaintext documents. You should generally be able to write new documentation |