diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Makefile | 155 | ||||
| -rw-r--r-- | docs/Readers.rst | 7 | ||||
| -rw-r--r-- | docs/design.rst | 55 | ||||
| -rw-r--r-- | docs/getting_started.rst | 4 | ||||
| -rw-r--r-- | docs/index.rst | 11 | ||||
| -rw-r--r-- | docs/open_projects.rst | 1 | ||||
| -rw-r--r-- | docs/windows_support.rst | 31 |
7 files changed, 18 insertions, 246 deletions
diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index 4c147eb11137..000000000000 --- a/docs/Makefile +++ /dev/null @@ -1,155 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = _build - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext - -all: html - -help: - @echo "Please use \`make <target>' where <target> is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - -clean: - -rm -rf $(BUILDDIR)/* - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/lld.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/lld.qhc" - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/lld" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/lld" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." diff --git a/docs/Readers.rst b/docs/Readers.rst index e00406b8c4ce..f9499635b72c 100644 --- a/docs/Readers.rst +++ b/docs/Readers.rst @@ -52,10 +52,9 @@ Where to start -------------- The lld project already has a skeleton of source code for Readers for -``ELF``, ``PECOFF``, ``MachO``, and lld's native Atom graph format -(both binary ``Native`` and ``YAML`` representations). If your file format -is a variant of one of those, you should modify the existing Reader to -support your variant. This is done by customizing the Options +``ELF``, ``PECOFF``, ``MachO``, and lld's native ``YAML`` graph format. +If your file format is a variant of one of those, you should modify the +existing Reader to support your variant. This is done by customizing the Options class for the Reader and making appropriate changes to the ``.cpp`` file to interpret those options and act accordingly. diff --git a/docs/design.rst b/docs/design.rst index 06d356527f58..408b8acaf890 100644 --- a/docs/design.rst +++ b/docs/design.rst @@ -300,60 +300,13 @@ and the ivars programmatically set. lld::File representations ------------------------- -Just as LLVM has three representations of its IR model, lld has three +Just as LLVM has three representations of its IR model, lld has two representations of its File/Atom/Reference model: * In memory, abstract C++ classes (lld::Atom, lld::Reference, and lld::File). * textual (in YAML) - * binary format ("native") - -Binary File Format -~~~~~~~~~~~~~~~~~~ - -In theory, lld::File objects could be written to disk in an existing Object File -format standard (e.g. ELF). Instead we choose to define a new binary file -format. There are two main reasons for this: fidelity and performance. In order -for lld to work as a linker on all platforms, its internal model must be rich -enough to model all CPU and OS linking features. But if we choose an existing -Object File format as the lld binary format, that means an on going need to -retrofit each platform specific feature needed from alternate platforms into the -existing Object File format. Having our own "native" binary format side steps -that issue. We still need to be able to binary encode all the features, but -once the in-memory model can represent the feature, it is straight forward to -binary encode it. - -The reason to use a binary file format at all, instead of a textual file format, -is speed. You want the binary format to be as fast as possible to read into the -in-memory model. Given that we control the in-memory model and the binary -format, the obvious way to make reading super fast it to make the file format be -basically just an array of atoms. The reader just mmaps in the file and looks -at the header to see how many atoms there are and instantiate that many atom -objects with the atom attribute information coming from that array. The trick -is designing this in a way that can be extended as the Atom mode evolves and new -attributes are added. - -The native object file format starts with a header that lists how many "chunks" -are in the file. A chunk is an array of "ivar data". The native file reader -instantiates an array of Atom objects (with one large malloc call). Each atom -contains just a pointer to its vtable and a pointer to its ivar data. All -methods on lld::Atom are virtual, so all the method implementations return -values based on the ivar data to which it has a pointer. If a new linking -features is added which requires a change to the lld::Atom model, a new native -reader class (e.g. version 2) is defined which knows how to read the new feature -information from the new ivar data. The old reader class (e.g. version 1) is -updated to do its best to model (the lack of the new feature) given the old ivar -data in existing native object files. - -With this model for the native file format, files can be read and turned -into the in-memory graph of lld::Atoms with just a few memory allocations. -And the format can easily adapt over time to new features. - -The binary file format follows the ReaderWriter patterns used in lld. The lld -library comes with the classes: ReaderNative and WriterNative. So, switching -between file formats is as easy as switching which Reader subclass is used. - Textual representations in YAML ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -406,11 +359,7 @@ test is a text file with comments telling lit how to run the test and check the result To facilitate testing, the lld project builds a tool called lld-core. This tool reads a YAML file (default from stdin), parses it into one or more lld::File objects in memory and then feeds those lld::File objects to the -resolver phase. The output of the resolver is written as a native object file. -It is then read back in using the native object file reader and then pass to the -YAML writer. This round-about path means that all three representations -(in-memory, binary, and text) are exercised, and any new feature has to work in -all the representations to pass the test. +resolver phase. Resolver testing diff --git a/docs/getting_started.rst b/docs/getting_started.rst index 986a406c1cb7..4b0e44e63a11 100644 --- a/docs/getting_started.rst +++ b/docs/getting_started.rst @@ -56,7 +56,7 @@ On Unix-like Systems 5. Test:: - $ make lld-test + $ make check-lld Using Visual Studio ~~~~~~~~~~~~~~~~~~~ @@ -64,7 +64,7 @@ Using Visual Studio #. Get the required tools. * `CMake 2.8`_\+. - * `Visual Studio 11 (2012) or later`_ (required for C++11 support) + * `Visual Studio 12 (2013) or later`_ (required for C++11 support) * `Python 2.4`_\+ (not 3.x) for running tests. .. _CMake 2.8: http://www.cmake.org/cmake/resources/software.html diff --git a/docs/index.rst b/docs/index.rst index 7a87ad8d0583..88c6f217531a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,15 +3,18 @@ lld - The LLVM Linker ===================== -lld is a new set of modular code for creating linker tools. +lld contains two linkers whose architectures are different from each other. +One is a linker that implements native features directly. +They are in `COFF` or `ELF` directories. Other directories contains the other +implementation that is designed to be a set of modular code for creating +linker tools. This document covers mainly the latter. +For the former, please read README.md in `COFF` directory. * End-User Features: * Compatible with existing linker options * Reads standard Object Files (e.g. ELF, Mach-O, PE/COFF) * Writes standard Executable Files (e.g. ELF, Mach-O, PE) - * Fast link times - * Minimal memory use * Remove clang's reliance on "the system linker" * Uses the LLVM `"UIUC" BSD-Style license`__. @@ -26,8 +29,6 @@ lld is a new set of modular code for creating linker tools. * Extensive unit tests * Internal linker model can be dumped/read to textual format - * Internal linker model can be dumped/read to a new native format - * Native format designed to be fast to read and write * Additional linking features can be plugged in as "passes" * OS specific and CPU specific code factored out diff --git a/docs/open_projects.rst b/docs/open_projects.rst index eb146c8b7542..448e967b5536 100644 --- a/docs/open_projects.rst +++ b/docs/open_projects.rst @@ -4,7 +4,6 @@ Open Projects ============= .. include:: ../include/lld/Core/TODO.txt -.. include:: ../lib/Core/TODO.txt .. include:: ../lib/Driver/TODO.rst .. include:: ../lib/ReaderWriter/ELF/X86_64/TODO.rst .. include:: ../lib/ReaderWriter/ELF/AArch64/TODO.rst diff --git a/docs/windows_support.rst b/docs/windows_support.rst index d9906a72ea1e..c4c338a0fba1 100644 --- a/docs/windows_support.rst +++ b/docs/windows_support.rst @@ -14,14 +14,14 @@ Windows support =============== -LLD has some experimental Windows support. When invoked as ``link.exe`` or with +LLD supports Windows operating system. When invoked as ``lld-link.exe`` or with ``-flavor link``, the driver for Windows operating system is used to parse command line options, and it drives further linking processes. LLD accepts almost all command line options that the linker shipped with Microsoft Visual C++ (link.exe) supports. -The current status is that LLD can link itself on Windows x86 using Visual C++ -2012 or 2013 as the compiler. +The current status is that LLD can link itself on Windows x86/x64 +using Visual C++ 2013 as the compiler. Development status ================== @@ -55,17 +55,12 @@ Windows resource files support COFF object file section. Both tools are shipped with MSVC. Safe Structured Exception Handler (SEH) - :good:`Done` for x86. :partial:`Work in progress` for x64. + :good:`Done` for both x86 and x64. Module-definition file :partial:`Partially done`. LLD currently recognizes these directives: ``EXPORTS``, ``HEAPSIZE``, ``STACKSIZE``, ``NAME``, and ``VERSION``. -x64 (x86-64) - :partial:`Work in progress`. LLD can create PE32+ executable but the generated - file does not work unless source object files are very simple because of the - lack of SEH handler table. - Debug info :none:`No progress has been made`. Microsoft linker can interpret the CodeGen debug info (old-style debug info) and PDB to emit an .pdb file. LLD doesn't @@ -86,7 +81,7 @@ Using Visual Studio IDE/MSBuild Alternatively, you can use msbuild if you don't like to work in an IDE:: msbuild LLVM.sln /m /target:"lld executables\lld" - + MSBuild.exe had been shipped as a component of the .NET framework, but since 2013 it's part of Visual Studio. You can find it at "C:\\Program Files (x86)\\msbuild". @@ -100,19 +95,3 @@ Using Ninja 1. Check out LLVM and LLD from the LLVM SVN repository (or Git mirror), #. run ``cmake -G ninja <llvm-source-dir>`` from VS command prompt, #. run ``ninja lld`` - -Known issues -============ - -Note that LLD is still in early stage in development, so there are still many -bugs. Here is a list of notable bugs. - -* Symbol name resolution from library files sometimes fails. On Windows, the - order of library files in command line does not matter, but LLD sometimes - fails to simulate the semantics. A workaround for it is to explicitly add - library files to command line with ``/DEFAULTLIB``. - -* Subsystem inference is not very reliable. Linker is supposed to set - ``subsystem`` field in the PE/COFF header according to entry function name, - but LLD sometimes ended up with ``unknown`` subsystem type. You need to give - ``/SUBSYSTEM`` option if it fails to infer it. |