Building Documentation#

The main GCC documentation uses Sphinx to generate pretty documentation from reStructuredText format. These are input for Manual pages format (make man), Info format (make info), HTML format (make html) and PDF format (make pdf).

Sphinx Install#

The ReST markups currently used by the documentation files are meant to be built with Sphinx version 5.3 or higher.

Most distributions are shipped with Sphinx, but its toolchain is fragile, and it is not uncommon that upgrading it or some other Python packages on your machine would cause the documentation build to break.

A way to avoid that is to use a different version than the one shipped with your distributions. In order to do so, it is recommended to install Sphinx inside a virtual environment, using virtualenv-3 or virtualenv, depending on how your distribution packaged Python 3.

$ virtualenv /tmp/venv
$ source /tmp/venv/bin/activate
$ pip install -r requirements.txt

Note the requirements.txt file is placed in gcc/doc folder and contains the following packages:


Then the virtualenv can be provided to the configure script --with-sphinx-build and will be used by the build system:

$ configure --with-sphinx-build=/tmp/venv/bin/sphinx-build

If you want to build the PDF documentation, you will need python3-Sphinx-latex sub-package.


When building manual and info pages (built by default), the only dependency is Sphinx package and one can ignore other dependencies mentioned in requirements.txt.

Writing Documentation#

Adding new documentation can be as simple as:

  1. Add a new .rst file somewhere under a doc subfolder.

  2. Refer to it from the Sphinx main TOC tree in a index.rst file.

This is usually good enough for simple documentation (like the one you’re reading right now), but for larger documents it may be advisable to create a subdirectory (or use an existing one).

See the documentation for Sphinx and reStructuredText on what you can do with them. In particular, the Sphinx reStructuredText Primer is a good place to get started with reStructuredText. There are also some Sphinx specific markup constructs and Usefull RST cheatsheet.

Specific guidelines for the GCC documentation#

Here are some specific guidelines for the GCC documentation:

  • Please stick to this order of heading adornments:

    1. = with overline for document title:

    Document title
    1. - for chapters:

    1. * for sections:

    1. ^ for subsections:

    1. ~ for subsubsections:


    Although RST doesn’t mandate a specific order (“Rather than imposing a fixed number and order of section title adornment styles, the order enforced will be the order as encountered.”), having the higher levels the same overall makes it easier to follow the documents.

  • For inserting fixed width text blocks (for code examples, use case examples, etc.), use :: for anything that doesn’t really benefit from syntax highlighting, especially short snippets. Use .. code-block:: <language> for longer code blocks that benefit from highlighting. For a short snippet of code embedded in the text, use ``code snippet``.

  • For parts of documentation that needs to be written or enhanced, use .. todo:: directive (part of the official sphinx.ext.todo extension). In development mode, all items are listed at the very end of the documentation for easier navigation.

GCC-specific directives and roles#

GCC uses its own extension ( that defined various directives. For the complete list of target-specific attributes, please take a look at the extension definition:




Generic GCC attribute


Function attribute


Variable attribute


Type attribute


Enumeral attribute


Label attribute


Target-specific function attribute (e.g. .. x86-fn-attr:: interrupt)


Target-specific variable attribute


Target-specific type attribute


GCC parameter directive, (e.g. .. gcc-param: inline-unit-growth)

Apart from the directives, we also define various inline roles:




Link to WG21 - The C++ Standards Committee (e.g. :P:`2003`)


Link to GCC bugzilla entry


Link to OpenMP documentation version $version (e.g. :openmp:`4.5`)


Link to OpenACC documentation version $version


Version of the documentation (e.g. 13.0.0, taken from BASE-VER)


Minimal required Sphinx version (e.g. 5.3, taken from


URL to bugzilla instance (e.g. “”""””)


Package version (e.g. (GCC))


Line break used for PDF version


Non-breaking space character

Miscellaneous Documentation#

In addition to the formal documentation that is installed by GCC, there are several other text files in the gcc subdirectory with miscellaneous documentation:


Notes on GCC’s Native Language Support.


this should be part of this manual rather than a separate file


Notes on the Free Translation Project.


The GNU General Public License, Versions 2 and 3.


The GNU Lesser General Public License, Versions 2.1 and 3.

*ChangeLog* */ChangeLog*

Change log files for various parts of GCC.


Details of a few changes to the GCC front-end interface.


the information in this file should be part of general documentation of the front-end interface in this manual.


Information about new features in old versions of GCC. (For recent versions, the information is on the GCC web site.)


Information about portability issues when writing code in GCC.


why isn’t this part of this manual or of the GCC Coding Conventions?


document such files in subdirectories, at least config, c, cp, objc, testsuite.