Building Documentation

This page explains how to build the documentation from source.

The documentation can be found in the ​RTEMS Documentation Repository. It contains ​README.txt and we suggest you also check it for the latest build instructions including host specific details.

Prerequisites

You will need:

• ​Sphinx - The Sphinx documentation system.
• ​Tex Live - The Tex Live document production system.
• ​Inliner - Single HTML Page Generator.

These tools may be provided by your host's packaging system or you may decide to install them manually.

The Tex Live system packaging may result in some fragility on your host system. It depends on how many and how the Tex Live packages are packaged for your host. If in doubt select the full install.

The RTEMS PDF output uses the lato and inconsolata fonts. These are not available on some hosts. If the configure phase of the build reports an error related to these Tex packages you can optionally disable support for them resulting in a lower quality documentation.

Sphinx

Note: Version 1.3 is the minimum version of Sphinx required and version 1.48 is recommended. We have found using a git release can have errors so we suggest avoiding it.

Windows users can find detailed instructions on the ​Sphinx Website.

Most UNIX distributions have a package for Sphinx. For manual installation refer to the ​Install Page on the Sphinx website.

 $ pip install -U sphinx

If you need to update pip use:

$ pip install --upgrade --user pip

You need to add into your your local copy of Sphinx:

export PATH=${HOME}/.local/bin:${PATH}

Tex Live

To install the Tex Live system from the upstream site run as root:

# cd /somewhere/temporary
# wget http://mirror.ctan.org/systems/texlive/tlnet/install-tl-unx.tar.gz
# tar xf install-tl-unx.tar.gz
# cd install-tl-20161106
# ./install-tl

NOTE: The date in the name of the directory will change.

• Use the command line system. Select O for options if you want to change from A4 to US letter paper size by default.
• Select I to install
• The tools will be installed into a directory like the following: /usr/local/texlive/2016/bin/i386-linux/. You will need to have a look to find the exact path.

Set the path to the install Tex Live system, make sure it is in front of other system paths:

export PATH=/usr/local/texlive/2016/bin/i386-linux/:${PATH}

Single HTML

The documentation can be built as a single HTML. This is a compact easy to reference way to view the documentation with some limitations:

• No searching.

• Section numbering is flat and does not match the HTML or PDF numbering.

Install the Node.js package manager for your platform. On FreeBSD the command is:

# pkg install npm

Once npm is installed install the Inliner package:

# npm install -g inliner

Getting Source

The source is located at:

• ​https://git.rtems.org/rtems-docs.git

$ cd
$ mkdir -p development/rtems/docs
$ cd development/rtems/docs
$ git clone git:://git.rtems.org/rtems-docs.git
$ cd rtems-docs

Building

You can build all document from the top level directory or you and enter a specific documents directory and build just that document. for the top level build:

$ ./waf configure
$ ./waf build

This will build the default html output which is a number of HTML files plus searching. The output will in the build directory under the manual's names and html.

You can add a prefix to the configure phase to install the output to the prefix:

$ ./waf configure --prefix=/opt/rtems/4.11
$ ./waf build install

Single HTML Output

A single HTML page can be built if the Inliner package is install by adding --singlehtml to the configure phase:

$ ./waf configure --singlehtml
$ ./waf build

PDF Output

PDF format output can be built is Tex Live and pdflatex is install by adding --pdf to the configure phase:

$ ./waf configure --pdf
$ ./waf build

All Output Formats

You can build all output formats at once by:

$ ./waf configure --prefix=/opt/rtems/4.11 --singlehtml --pdf
$ ./waf build install

Sphinx Warnings

To see the Sphinx warnings use the --sphinx-verbose= option. Refer to the Sphinx documentation for the available options. The simplest is to add -v, for example:

$ ./waf configure --sphinx-verbose=-v
$ ./waf build 

PDF Fonts

If your host does not provide the extra fonts we use for a better quality output you can override the configure phase and fall back to use lower quality fonts by adding:

$ ./waf configure --disable-extra-fonts
$ ./waf build 

If the fonts are found on your host the option is ignored.