Index: README.md =================================================================== --- README.md +++ README.md @@ -1,6 +1,5 @@ - LLVM Linker (lld) -============================== +================= This directory and its subdirectories contain source code for the LLVM Linker, a modular cross platform linker which is built as part of the LLVM compiler Index: docs/NewLLD.rst =================================================================== --- docs/NewLLD.rst +++ docs/NewLLD.rst @@ -57,59 +57,61 @@ * 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,9 +138,9 @@ 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. * Symbol @@ -173,7 +175,8 @@ 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 @@ -216,10 +219,10 @@ * 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 @@ -227,7 +230,8 @@ - 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. Index: docs/sphinx_intro.rst =================================================================== --- docs/sphinx_intro.rst +++ docs/sphinx_intro.rst @@ -57,41 +57,21 @@ 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