diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/BitCodeFormat.rst | 49 | ||||
| -rw-r--r-- | docs/DeveloperPolicy.rst | 3 | ||||
| -rw-r--r-- | docs/ExtendingLLVM.rst | 4 | ||||
| -rw-r--r-- | docs/GettingStarted.rst | 64 | ||||
| -rw-r--r-- | docs/HowToSetUpLLVMStyleRTTI.rst | 141 | ||||
| -rw-r--r-- | docs/Lexicon.rst | 13 | ||||
| -rw-r--r-- | docs/Phabricator.rst | 94 | ||||
| -rw-r--r-- | docs/SphinxQuickstartTemplate.rst | 125 | ||||
| -rw-r--r-- | docs/userguides.rst | 6 |
9 files changed, 417 insertions, 82 deletions
diff --git a/docs/BitCodeFormat.rst b/docs/BitCodeFormat.rst index d3995e7036b..bd26f7b1502 100644 --- a/docs/BitCodeFormat.rst +++ b/docs/BitCodeFormat.rst @@ -489,6 +489,8 @@ The magic number for LLVM IR files is: When combined with the bitcode magic number and viewed as bytes, this is ``"BC 0xC0DE"``. +.. _Signed VBRs: + Signed VBRs ^^^^^^^^^^^ @@ -507,6 +509,7 @@ As such, signed VBR values of a specific width are emitted as follows: With this encoding, small positive and small negative values can both be emitted efficiently. Signed VBR encoding is used in ``CST_CODE_INTEGER`` and ``CST_CODE_WIDE_INTEGER`` records within ``CONSTANTS_BLOCK`` blocks. +It is also used for phi instruction operands in `MODULE_CODE_VERSION`_ 1. LLVM IR Blocks ^^^^^^^^^^^^^^ @@ -553,13 +556,57 @@ block may contain the following sub-blocks: * `FUNCTION_BLOCK`_ * `METADATA_BLOCK`_ +.. _MODULE_CODE_VERSION: + MODULE_CODE_VERSION Record ^^^^^^^^^^^^^^^^^^^^^^^^^^ ``[VERSION, version#]`` The ``VERSION`` record (code 1) contains a single value indicating the format -version. Only version 0 is supported at this time. +version. Versions 0 and 1 are supported at this time. The difference between +version 0 and 1 is in the encoding of instruction operands in +each `FUNCTION_BLOCK`_. + +In version 0, each value defined by an instruction is assigned an ID +unique to the function. Function-level value IDs are assigned starting from +``NumModuleValues`` since they share the same namespace as module-level +values. The value enumerator resets after each function. When a value is +an operand of an instruction, the value ID is used to represent the operand. +For large functions or large modules, these operand values can be large. + +The encoding in version 1 attempts to avoid large operand values +in common cases. Instead of using the value ID directly, operands are +encoded as relative to the current instruction. Thus, if an operand +is the value defined by the previous instruction, the operand +will be encoded as 1. + +For example, instead of + +.. code-block:: llvm + + #n = load #n-1 + #n+1 = icmp eq #n, #const0 + br #n+1, label #(bb1), label #(bb2) + +version 1 will encode the instructions as + +.. code-block:: llvm + + #n = load #1 + #n+1 = icmp eq #1, (#n+1)-#const0 + br #1, label #(bb1), label #(bb2) + +Note in the example that operands which are constants also use +the relative encoding, while operands like basic block labels +do not use the relative encoding. + +Forward references will result in a negative value. +This can be inefficient, as operands are normally encoded +as unsigned VBRs. However, forward references are rare, except in the +case of phi instructions. For phi instructions, operands are encoded as +`Signed VBRs`_ to deal with forward references. + MODULE_CODE_TRIPLE Record ^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/DeveloperPolicy.rst b/docs/DeveloperPolicy.rst index f940dbc579a..e35e7295564 100644 --- a/docs/DeveloperPolicy.rst +++ b/docs/DeveloperPolicy.rst @@ -137,6 +137,9 @@ reviewees. If someone is kind enough to review your code, you should return the favor for someone else. Note that anyone is welcome to review and give feedback on a patch, but only people with Subversion write access can approve it. +There is a web based code review tool that can optionally be used +for code reviews. See :doc:`Phabricator`. + Code Owners ----------- diff --git a/docs/ExtendingLLVM.rst b/docs/ExtendingLLVM.rst index e41cfd996e5..6df08eee985 100644 --- a/docs/ExtendingLLVM.rst +++ b/docs/ExtendingLLVM.rst @@ -270,7 +270,7 @@ Adding a derived type add support for derived type to: - .. code:: c++ + .. code-block:: c++ std::string getTypeDescription(const Type &Ty, std::vector<const Type*> &TypeStack) @@ -296,7 +296,7 @@ Adding a derived type modify - .. code:: c++ + .. code-block:: c++ void calcTypeName(const Type *Ty, std::vector<const Type*> &TypeStack, diff --git a/docs/GettingStarted.rst b/docs/GettingStarted.rst index d78c78f1cc2..68768921f6a 100644 --- a/docs/GettingStarted.rst +++ b/docs/GettingStarted.rst @@ -505,7 +505,7 @@ directory: If you would like to get the LLVM test suite (a separate package as of 1.4), you get it from the Subversion repository: -.. code:: bash +.. code-block:: bash % cd llvm/projects % svn co http://llvm.org/svn/llvm-project/test-suite/trunk test-suite @@ -523,13 +523,13 @@ marks (so, you can recreate git-svn metadata locally). Note that right now mirrors reflect only ``trunk`` for each project. You can do the read-only GIT clone of LLVM via: -.. code:: bash +.. code-block:: bash % git clone http://llvm.org/git/llvm.git If you want to check out clang too, run: -.. code:: bash +.. code-block:: bash % git clone http://llvm.org/git/llvm.git % cd llvm/tools @@ -540,26 +540,26 @@ pull --rebase`` instead of ``git pull`` to avoid generating a non-linear history in your clone. To configure ``git pull`` to pass ``--rebase`` by default on the master branch, run the following command: -.. code:: bash +.. code-block:: bash % git config branch.master.rebase true Sending patches with Git ^^^^^^^^^^^^^^^^^^^^^^^^ -Please read `Developer Policy <DeveloperPolicy.html#patches>`_, too. +Please read `Developer Policy <DeveloperPolicy.html#one-off-patches>`_, too. Assume ``master`` points the upstream and ``mybranch`` points your working branch, and ``mybranch`` is rebased onto ``master``. At first you may check sanity of whitespaces: -.. code:: bash +.. code-block:: bash % git diff --check master..mybranch The easiest way to generate a patch is as below: -.. code:: bash +.. code-block:: bash % git diff master..mybranch > /path/to/mybranch.diff @@ -570,20 +570,20 @@ could be accepted with ``patch -p1 -N``. But you may generate patchset with git-format-patch. It generates by-each-commit patchset. To generate patch files to attach to your article: -.. code:: bash +.. code-block:: bash % git format-patch --no-attach master..mybranch -o /path/to/your/patchset If you would like to send patches directly, you may use git-send-email or git-imap-send. Here is an example to generate the patchset in Gmail's [Drafts]. -.. code:: bash +.. code-block:: bash % git format-patch --attach master..mybranch --stdout | git imap-send Then, your .git/config should have [imap] sections. -.. code:: bash +.. code-block:: bash [imap] host = imaps://imap.gmail.com @@ -594,16 +594,16 @@ Then, your .git/config should have [imap] sections. ; in English folder = "[Gmail]/Drafts" ; example for Japanese, "Modified UTF-7" encoded. - folder = "[Gmail]/&Tgtm+DBN-" + folder = "[Gmail]/&Tgtm+DBN-" ; example for Traditional Chinese - folder = "[Gmail]/&g0l6Pw-" + folder = "[Gmail]/&g0l6Pw-" For developers to work with git-svn ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To set up clone from which you can submit code using ``git-svn``, run: -.. code:: bash +.. code-block:: bash % git clone http://llvm.org/git/llvm.git % cd llvm @@ -622,7 +622,7 @@ To set up clone from which you can submit code using ``git-svn``, run: To update this clone without generating git-svn tags that conflict with the upstream git repo, run: -.. code:: bash +.. code-block:: bash % git fetch && (cd tools/clang && git fetch) # Get matching revisions of both trees. % git checkout master @@ -640,7 +640,7 @@ The git-svn metadata can get out of sync after you mess around with branches and ``dcommit``. When that happens, ``git svn dcommit`` stops working, complaining about files with uncommitted changes. The fix is to rebuild the metadata: -.. code:: bash +.. code-block:: bash % rm -rf .git/svn % git svn rebase -l @@ -722,13 +722,13 @@ To configure LLVM, follow these steps: #. Change directory into the object root directory: - .. code:: bash + .. code-block:: bash % cd OBJ_ROOT #. Run the ``configure`` script located in the LLVM source tree: - .. code:: bash + .. code-block:: bash % SRC_ROOT/configure --prefix=/install/path [other options] @@ -764,7 +764,7 @@ Profile Builds Once you have LLVM configured, you can build it by entering the *OBJ_ROOT* directory and issuing the following command: -.. code:: bash +.. code-block:: bash % gmake @@ -775,7 +775,7 @@ If you have multiple processors in your machine, you may wish to use some of the parallel build options provided by GNU Make. For example, you could use the command: -.. code:: bash +.. code-block:: bash % gmake -j2 @@ -866,13 +866,13 @@ This is accomplished in the typical autoconf manner: * Change directory to where the LLVM object files should live: - .. code:: bash + .. code-block:: bash % cd OBJ_ROOT * Run the ``configure`` script found in the LLVM source directory: - .. code:: bash + .. code-block:: bash % SRC_ROOT/configure @@ -918,7 +918,7 @@ module, and you have root access on the system, you can set your system up to execute LLVM bitcode files directly. To do this, use commands like this (the first command may not be required if you are already using the module): -.. code:: bash +.. code-block:: bash % mount -t binfmt_misc none /proc/sys/fs/binfmt_misc % echo ':llvm:M::BC::/path/to/lli:' > /proc/sys/fs/binfmt_misc/register @@ -928,7 +928,7 @@ first command may not be required if you are already using the module): This allows you to execute LLVM bitcode files directly. On Debian, you can also use this command instead of the 'echo' command above: -.. code:: bash +.. code-block:: bash % sudo update-binfmts --install llvm /path/to/lli --magic 'BC' @@ -1208,7 +1208,7 @@ Example with clang #. First, create a simple C file, name it 'hello.c': - .. code:: c + .. code-block:: c #include <stdio.h> @@ -1219,7 +1219,7 @@ Example with clang #. Next, compile the C file into a native executable: - .. code:: bash + .. code-block:: bash % clang hello.c -o hello @@ -1230,7 +1230,7 @@ Example with clang #. Next, compile the C file into a LLVM bitcode file: - .. code:: bash + .. code-block:: bash % clang -O3 -emit-llvm hello.c -c -o hello.bc @@ -1240,13 +1240,13 @@ Example with clang #. Run the program in both forms. To run the program, use: - .. code:: bash + .. code-block:: bash % ./hello and - .. code:: bash + .. code-block:: bash % lli hello.bc @@ -1255,19 +1255,19 @@ Example with clang #. Use the ``llvm-dis`` utility to take a look at the LLVM assembly code: - .. code:: bash + .. code-block:: bash % llvm-dis < hello.bc | less #. Compile the program to native assembly using the LLC code generator: - .. code:: bash + .. code-block:: bash % llc hello.bc -o hello.s #. Assemble the native assembly language file into a program: - .. code:: bash + .. code-block:: bash **Solaris:** % /opt/SUNWspro/bin/cc -xarch=v9 hello.s -o hello.native @@ -1275,7 +1275,7 @@ Example with clang #. Execute the native code program: - .. code:: bash + .. code-block:: bash % ./hello.native diff --git a/docs/HowToSetUpLLVMStyleRTTI.rst b/docs/HowToSetUpLLVMStyleRTTI.rst index b5c1b78afeb..aa1ad84afee 100644 --- a/docs/HowToSetUpLLVMStyleRTTI.rst +++ b/docs/HowToSetUpLLVMStyleRTTI.rst @@ -65,10 +65,9 @@ steps: #include "llvm/Support/Casting.h" - #. In the base class, introduce an enum which discriminates all of the - different classes in the hierarchy, and stash the enum value somewhere in - the base class. + different concrete classes in the hierarchy, and stash the enum value + somewhere in the base class. Here is the code after introducing this change: @@ -78,8 +77,8 @@ steps: public: + /// Discriminator for LLVM-style RTTI (dyn_cast<> et al.) + enum ShapeKind { - + SquareKind, - + CircleKind + + SK_Square, + + SK_Circle + }; +private: + const ShapeKind Kind; @@ -103,7 +102,7 @@ steps: You might wonder why the ``Kind`` enum doesn't have an entry for ``Shape``. The reason for this is that since ``Shape`` is abstract (``computeArea() = 0;``), you will never actually have non-derived - instances of exactly that class (only subclasses). See `Concrete Bases + instances of exactly that class (only subclasses). See `Concrete Bases and Deeper Hierarchies`_ for information on how to deal with non-abstract bases. It's worth mentioning here that unlike ``dynamic_cast<>``, LLVM-style RTTI can be used (and is often used) for @@ -122,8 +121,8 @@ steps: public: /// Discriminator for LLVM-style RTTI (dyn_cast<> et al.) enum ShapeKind { - SquareKind, - CircleKind + SK_Square, + SK_Circle }; private: const ShapeKind Kind; @@ -139,7 +138,7 @@ steps: double SideLength; public: - Square(double S) : SideLength(S) {} - + Square(double S) : Shape(SquareKind), SideLength(S) {} + + Square(double S) : Shape(SK_Square), SideLength(S) {} double computeArea() /* override */; }; @@ -147,7 +146,7 @@ steps: double Radius; public: - Circle(double R) : Radius(R) {} - + Circle(double R) : Shape(CircleKind), Radius(R) {} + + Circle(double R) : Shape(SK_Circle), Radius(R) {} double computeArea() /* override */; }; @@ -164,8 +163,8 @@ steps: public: /// Discriminator for LLVM-style RTTI (dyn_cast<> et al.) enum ShapeKind { - SquareKind, - CircleKind + SK_Square, + SK_Circle }; private: const ShapeKind Kind; @@ -174,53 +173,72 @@ steps: Shape(ShapeKind K) : Kind(K) {} virtual double computeArea() = 0; - + - + static bool classof(const Shape *) { return true; } }; class Square : public Shape { double SideLength; public: - Square(double S) : Shape(SquareKind), SideLength(S) {} + Square(double S) : Shape(SK_Square), SideLength(S) {} double computeArea() /* override */; + - + static bool classof(const Square *) { return true; } + static bool classof(const Shape *S) { - + return S->getKind() == SquareKind; + + return S->getKind() == SK_Square; + } }; class Circle : public Shape { double Radius; public: - Circle(double R) : Shape(CircleKind), Radius(R) {} + Circle(double R) : Shape(SK_Circle), Radius(R) {} double computeArea() /* override */; + - + static bool classof(const Circle *) { return true; } + static bool classof(const Shape *S) { - + return S->getKind() == CircleKind; + + return S->getKind() == SK_Circle; + } }; - Basically, the job of ``classof`` is to return ``true`` if its argument - is of the enclosing class's type. As you can see, there are two general - overloads of ``classof`` in use here. + The job of ``classof`` is to dynamically determine whether an object of + a base class is in fact of a particular derived class. In order to + downcast a type ``Base`` to a type ``Derived``, there needs to be a + ``classof`` in ``Derived`` which will accept an object of type ``Base``. + + To be concrete, consider the following code: + + .. code-block:: c++ + + Shape *S = ...; + if (isa<Circle>(S)) { + /* do something ... */ + } - #. The first, which just returns ``true``, means that if we know that the - argument of the cast is of the enclosing type *at compile time*, then - we don't need to bother to check anything since we already know that - the type is convertible. This is an optimization for the case that we - statically know the conversion is OK. + The code of the ``isa<>`` test in this code will eventually boil + down---after template instantiation and some other machinery---to a + check roughly like ``Circle::classof(S)``. For more information, see + :ref:`classof-contract`. - #. The other overload takes a pointer to an object of the base of the - class hierarchy: this is the "general case" of the cast. We need to - check the ``Kind`` to dynamically decide if the argument is of (or - derived from) the enclosing type. + The argument to ``classof`` should always be an *ancestor* class because + the implementation has logic to allow and optimize away + upcasts/up-``isa<>``'s automatically. It is as though every class + ``Foo`` automatically has a ``classof`` like: + + .. code-block:: c++ - To be more precise, let ``classof`` be inside a class ``C``. Then the - contract for ``classof`` is "return ``true`` if the argument is-a - ``C``". As long as your implementation fulfills this contract, you can - tweak and optimize it as much as you want. + class Foo { + [...] + template <class T> + static bool classof(const T *, + ::llvm::enable_if_c< + ::llvm::is_base_of<Foo, T>::value + >::type* = 0) { return true; } + [...] + }; + + Note that this is the reason that we did not need to introduce a + ``classof`` into ``Shape``: all relevant classes derive from ``Shape``, + and ``Shape`` itself is abstract (has no entry in the ``Kind`` enum), + so this notional inferred ``classof`` is all we need. See `Concrete + Bases and Deeper Hierarchies`_ for more information about how to extend + this example to more general hierarchies. Although for this small example setting up LLVM-style RTTI seems like a lot of "boilerplate", if your classes are doing anything interesting then this @@ -231,29 +249,37 @@ Concrete Bases and Deeper Hierarchies For concrete bases (i.e. non-abstract interior nodes of the inheritance tree), the ``Kind`` check inside ``classof`` needs to be a bit more -complicated. Say that ``SpecialSquare`` and ``OtherSpecialSquare`` derive +complicated. The situation differs from the example above in that + +* Since the class is concrete, it must itself have an entry in the ``Kind`` + enum because it is possible to have objects with this class as a dynamic + type. + +* Since the class has children, the check inside ``classof`` must take them + into account. + +Say that ``SpecialSquare`` and ``OtherSpecialSquare`` derive from ``Square``, and so ``ShapeKind`` becomes: .. code-block:: c++ enum ShapeKind { - SquareKind, - + SpecialSquareKind, - + OtherSpecialSquareKind, - CircleKind + SK_Square, + + SK_SpecialSquare, + + SK_OtherSpecialSquare, + SK_Circle } Then in ``Square``, we would need to modify the ``classof`` like so: .. code-block:: c++ - static bool classof(const Square *) { return true; } - static bool classof(const Shape *S) { - - return S->getKind() == SquareKind; + - return S->getKind() == SK_Square; - } + static bool classof(const Shape *S) { - + return S->getKind() >= SquareKind && - + S->getKind() <= OtherSpecialSquareKind; + + return S->getKind() >= SK_Square && + + S->getKind() <= SK_OtherSpecialSquare; + } The reason that we need to test a range like this instead of just equality @@ -273,9 +299,34 @@ ordering right:: | OtherSpecialSquare | Circle +.. _classof-contract: + +The Contract of ``classof`` +--------------------------- + +To be more precise, let ``classof`` be inside a class ``C``. Then the +contract for ``classof`` is "return ``true`` if the dynamic type of the +argument is-a ``C``". As long as your implementation fulfills this +contract, you can tweak and optimize it as much as you want. + .. TODO:: Touch on some of the more advanced features, like ``isa_impl`` and ``simplify_type``. However, those two need reference documentation in the form of doxygen comments as well. We need the doxygen so that we can say "for full details, see http://llvm.org/doxygen/..." + +Rules of Thumb +============== + +#. The ``Kind`` enum should have one entry per concrete class, ordered + according to a preorder traversal of the inheritance tree. +#. The argument to ``classof`` should be a ``const Base *``, where ``Base`` + is some ancestor in the inheritance hierarchy. The argument should + *never* be a derived class or the class itself: the template machinery + for ``isa<>`` already handles this case and optimizes it. +#. For each class in the hierarchy that has no children, implement a + ``classof`` that checks only against its ``Kind``. +#. For each class in the hierarchy that has children, implement a + ``classof`` that checks a range of the first child's ``Kind`` and the + last child's ``Kind``. diff --git a/docs/Lexicon.rst b/docs/Lexicon.rst index 6ebe61429f9..d568c0b302e 100644 --- a/docs/Lexicon.rst +++ b/docs/Lexicon.rst @@ -20,8 +20,10 @@ A B - -**BURS** +**BB Vectorization** + Basic Block Vectorization +**BURS** Bottom Up Rewriting System --- A method of instruction selection for code generation. An example is the `BURG <http://www.program-transformation.org/Transform/BURG>`_ tool. @@ -156,7 +158,7 @@ R In garbage collection, a pointer variable lying outside of the `heap`_ from which the collector begins its reachability analysis. In the context of code generation, "root" almost always refers to a "stack root" --- a local or - temporary variable within an executing function.</dd> + temporary variable within an executing function. **RPO** Reverse postorder @@ -192,3 +194,10 @@ S **Stack Map** In garbage collection, metadata emitted by the code generator which identifies `roots`_ within the stack frame of an executing function. + +T +- + +**TBAA** + Type-Based Alias Analysis + diff --git a/docs/Phabricator.rst b/docs/Phabricator.rst new file mode 100644 index 00000000000..cd984b09be3 --- /dev/null +++ b/docs/Phabricator.rst @@ -0,0 +1,94 @@ +============================= +Code Reviews with Phabricator +============================= + +.. contents:: + :local: + +If you prefer to use a web user interface for code reviews, +you can now submit your patches for Clang and LLVM at +`LLVM's Phabricator`_. + +Sign up +------- + +Sign up with one of the supported OAuth account types. If +you use your Subversion user name as Phabricator user name, +Phabricator will automatically connect your submits to your +Phabricator user in the `Code Repository Browser`_. + + +Requesting a review via the command line +---------------------------------------- + +Phabricator has a tool called *Arcanist* to upload patches from +the command line. To get you set up, follow the +`Arcanist Quick Start`_ instructions. + +You can learn more about how to use arc to interact with +Phabricator in the `Arcanist User Guide`_. + +Requesting a review via the web interface +----------------------------------------- + +The tool to create and review patches in Phabricator is called +*Differential*. + +Note that you can upload patches created through various diff tools, +including git and svn. To make reviews easier, please always include +**as much context as possible** with your diff! Don't worry, Phabricator +will automatically send a diff with a smaller context in the review +email, but having the full file in the web interface will help the +reviewer understand your code. + +To get a full diff, use one of the following commands (or just use Arcanist +to upload your patch): + +* git diff -U999999 other-branch +* svn diff --diff-cmd=diff -x -U999999 + +To upload a new patch: + +* Click *Differential*. +* Click *Create Revision*. +* Paste the text diff or upload the patch file. + Note that TODO +* Leave the drop down on *Create a new Revision...* and click *Continue*. +* Enter a descriptive title and summary; add reviewers and mailing + lists that you want to be included in the review. If your patch is + for LLVM, cc llvm-commits; if your patch is for Clang, cc cfe-commits. +* Click *Save*. + +To submit an updated patch: + +* Click *Differential*. +* Click *Create Revision*. +* Paste the updated diff. +* Select the review you want to from the *Attach To* dropdown and click + *Continue*. +* Click *Save*. + +Reviewing code with Phabricator +------------------------------- + +Phabricator allows you to add inline comments as well as overall comments +to a revision. To add an inline comment, select the lines of code you want +to comment on by clicking and dragging the line numbers in the diff pane. + +You can add overall comments or submit your comments at the bottom of the page. + +Phabricator has many useful features, for example allowing you to select +diffs between different versions of the patch as it was reviewed in the +*Revision Update History*. Most features are self descriptive - explore, and +if you have a question, drop by on #llvm in IRC to get help. + +Status +------ + +Currently, we're testing Phabricator for use with Clang/LLVM. Please let us +know whether you like it and what could be improved! + +.. _LLVM's Phabricator: http://llvm-reviews.chandlerc.com +.. _Code Repository Browser: http://llvm-reviews.chandlerc.com/diffusion/ +.. _Arcanist Quick Start: http://www.phabricator.com/docs/phabricator/article/Arcanist_Quick_Start.html +.. _Arcanist User Guide: http://www.phabricator.com/docs/phabricator/article/Arcanist_User_Guide.html diff --git a/docs/SphinxQuickstartTemplate.rst b/docs/SphinxQuickstartTemplate.rst new file mode 100644 index 00000000000..75d916368e3 --- /dev/null +++ b/docs/SphinxQuickstartTemplate.rst @@ -0,0 +1,125 @@ +========================== +Sphinx Quickstart Template +========================== + +.. sectionauthor:: Sean Silva <silvas@purdue.edu> + +Introduction and Quickstart +=========================== + +This document is meant to get you writing documentation as fast as possible +even if you have no previous experience with Sphinx. The goal is to take +someone in the state of "I want to write documentation and get it added to +LLVM's docs" and turn that into useful documentation mailed to llvm-commits +with as little nonsense as possible. + +You can find this document in ``docs/SphinxQuickstartTemplate.rst``. You +should copy it, open the new file in your text editor, write your docs, and +then send the new document to llvm-commits for review. + +Focus on *content*. It is easy to fix the Sphinx (reStructuredText) syntax +later if necessary, although reStructuredText tries to imitate common +plain-text conventions so it should be quite natural. A basic knowledge of +reStructuredText syntax is useful when writing the document, so the last +~half of this document (starting with `Example Section`_) gives examples +which should cover 99% of use cases. + +Let me say that again: focus on *content*. + +Once you have finished with the content, please send the ``.rst`` file to +llvm-commits for review. + +Guidelines +========== + +Try to answer the following questions in your first section: + +#. Why would I want to read this document? + +#. What should I know to be able to follow along with this document? + +#. What will I have learned by the end of this document? + +Common names for the first section are ``Introduction``, ``Overview``, or +``Background``. + +If possible, make your document a "how to". Give it a name ``HowTo*.rst`` +like the other "how to" documents. This format is usually the easiest +for another person to understand and also the most useful. + +You generally should not be writing documentation other than a "how to" +unless there is already a "how to" about your topic. The reason for this +is that without a "how to" document to read first, it is difficult for a +person to understand a more advanced document. + +Focus on content (yes, I had to say it again). + +The rest of this document shows example reStructuredText markup constructs +that are meant to be read by you in your text editor after you have copied +this file into a new file for the documentation you are about to write. + +Example Section +=============== + +Your text can be *emphasized*, **bold**, or ``monospace``. + +Use blank lines to separate paragraphs. + +Headings (like ``Example Section`` just above) give your document +structure. Use the same kind of adornments (e.g. ``======`` vs. ``------``) +as are used in this document. The adornment must be the same length as the +text above it. For Vim users, variations of ``yypVr=`` might be handy. + +Example Subsection +------------------ + +Make a link `like this <http://llvm.org/>`_. There is also a more +sophisticated syntax which `can be more readable`_ for longer links since +it disrupts the flow less. You can put the ``.. _`link text`: <URL>`` block +pretty much anywhere later in the document. + +.. _`can be more readable`: http://en.wikipedia.org/wiki/LLVM + +Lists can be made like this: + +#. A list starting with ``#.`` will be automatically numbered. + +#. This is a second list element. + + #. They nest too. + +You can also use unordered lists. + +* Stuff. + + + Deeper stuff. + +* More stuff. + +Example Subsubsection +^^^^^^^^^^^^^^^^^^^^^ + +You can make blocks of code like this: + +.. code-block:: c++ + + int main() { + return 0 + } + +For a shell session, use a ``bash`` code block: + +.. code-block:: bash + + $ echo "Goodbye cruel world!" + $ rm -rf / + +If you need to show LLVM IR use the ``llvm`` code block. + +Hopefully you won't need to be this deep +"""""""""""""""""""""""""""""""""""""""" + +If you need to do fancier things than what has been shown in this document, +you can mail the list or check Sphinx's `reStructuredText Primer`_. + +.. _`reStructuredText Primer`: http://sphinx.pocoo.org/rest.html diff --git a/docs/userguides.rst b/docs/userguides.rst index 6ff46ade480..8c1554dfce9 100644 --- a/docs/userguides.rst +++ b/docs/userguides.rst @@ -18,6 +18,8 @@ User Guides HowToAddABuilder yaml2obj HowToSubmitABug + SphinxQuickstartTemplate + Phabricator * :ref:`getting_started` @@ -70,6 +72,10 @@ User Guides Instructions for properly submitting information about any bugs you run into in the LLVM system. +* :doc:`SphinxQuickstartTemplate` + + A template + tutorial for writing new Sphinx documentation. It is meant + to be read in source form. * `LLVM Testing Infrastructure Guide <TestingGuide.html>`_ |