[rtems-docs commit] user: Remove nit-picky warnings.
Chris Johns
chrisj at rtems.org
Thu Feb 28 22:58:26 UTC 2019
Module: rtems-docs
Branch: master
Commit: 2674d6a949447e5874bf47d152bdca57d09a3864
Changeset: http://git.rtems.org/rtems-docs/commit/?id=2674d6a949447e5874bf47d152bdca57d09a3864
Author: Chris Johns <chrisj at rtems.org>
Date: Thu Feb 21 13:06:58 2019 +1100
user: Remove nit-picky warnings.
---
user/bsps/bsps-powerpc.rst | 4 +-
user/bsps/bsps-x86_64.rst | 16 +-
user/exe/debugging.rst | 2 +-
user/exe/index.rst | 12 +-
user/exe/initialization.rst | 4 +-
user/exe/loader.rst | 23 ++-
user/hosts/macos.rst | 5 +-
user/hosts/os.rst | 3 +-
user/hosts/posix.rst | 87 ++++++-----
user/hosts/windows.rst | 93 +++++------
user/installation/kernel.rst | 7 +-
user/overview/index.rst | 2 +
user/rsb/bug-reporting.rst | 2 +-
user/rsb/commands.rst | 26 ++--
user/rsb/configuration.rst | 311 ++++++++++++++++++++++++-------------
user/rsb/cross-canadian-cross.rst | 32 ++--
user/rsb/deployment.rst | 14 +-
user/rsb/history.rst | 2 +-
user/rsb/index.rst | 8 +-
user/rsb/project-sets.rst | 40 +++--
user/rsb/third-party-packages.rst | 40 +++--
user/rsb/why-build-from-source.rst | 2 +-
user/start/index.rst | 2 -
user/testing/configuration.rst | 21 ++-
user/testing/consoles.rst | 2 +-
user/testing/gdb-jtag.rst | 2 +-
user/testing/index.rst | 14 +-
user/testing/tests.rst | 15 ++
user/testing/tftp.rst | 29 ++--
user/tracing/captureengine.rst | 2 +-
user/tracing/examples.rst | 10 +-
user/tracing/introduction.rst | 2 +-
user/tracing/tracelinker.rst | 12 +-
user/wscript | 8 +-
34 files changed, 541 insertions(+), 313 deletions(-)
diff --git a/user/bsps/bsps-powerpc.rst b/user/bsps/bsps-powerpc.rst
index 0ee51d1..365571f 100644
--- a/user/bsps/bsps-powerpc.rst
+++ b/user/bsps/bsps-powerpc.rst
@@ -94,7 +94,7 @@ Boot via U-Boot
The application executable file (ELF file) must be converted to an U-Boot
image. Use the following commands:
-::
+.. code-block:: shell
powerpc-rtems5-objcopy -O binary app.exe app.bin
gzip -9 -f -c app.bin > app.bin.gz
@@ -102,7 +102,7 @@ image. Use the following commands:
Use the following U-Boot commands to boot an application via TFTP download:
-::
+.. code-block:: shell
tftpboot ${loadaddr} app.img && run loadfdt && bootm ${loadaddr} - ${fdt_addr} ; reset
diff --git a/user/bsps/bsps-x86_64.rst b/user/bsps/bsps-x86_64.rst
index 3942307..c872734 100644
--- a/user/bsps/bsps-x86_64.rst
+++ b/user/bsps/bsps-x86_64.rst
@@ -49,7 +49,7 @@ Quick instructions (which may fall out of date) are:
Then edit ``Conf/target.txt`` to set:
-::
+.. code-block:: ini
ACTIVE_PLATFORM = OvmfPkg/OvmfPkgX64.dsc
TARGET = DEBUG
@@ -67,7 +67,7 @@ You can find the ``OVMF.fd`` file like this as well in the edk2 directory:
$ find . -name "*.fd"
./Build/OvmfX64/DEBUG_GCC5/FV/MEMFD.fd
- ./Build/OvmfX64/DEBUG_GCC5/FV/OVMF.fd <-- the file we're looking for
+ ./Build/OvmfX64/DEBUG_GCC5/FV/OVMF.fd # the file we're looking for
./Build/OvmfX64/DEBUG_GCC5/FV/OVMF_CODE.fd
./Build/OvmfX64/DEBUG_GCC5/FV/OVMF_VARS.fd
@@ -84,12 +84,12 @@ replacing paths as appropriate.
.. code-block:: shell
- $ qemu-img create freebsd.img 8G
- $ OVMF_LOCATION=/path/to/ovmf/OVMF.fd
- $ FREEBSD_MEMSTICK=/path/to/FreeBSD-11.2-amd64-memstick.img
- $ qemu-system-x86_64 -m 1024 -serial stdio --bios $OVMF_LOCATION \
- -drive format=raw,file=freebsd.img \
- -drive format=raw,file=$FREEBSD_MEMSTICK
+ $ qemu-img create freebsd.img 8G
+ $ OVMF_LOCATION=/path/to/ovmf/OVMF.fd
+ $ FREEBSD_MEMSTICK=/path/to/FreeBSD-11.2-amd64-memstick.img
+ $ qemu-system-x86_64 -m 1024 -serial stdio --bios $OVMF_LOCATION \
+ -drive format=raw,file=freebsd.img \
+ -drive format=raw,file=$FREEBSD_MEMSTICK
The first time you do this, continue through and install FreeBSD. `FreeBSD's
installation guide may prove useful
diff --git a/user/exe/debugging.rst b/user/exe/debugging.rst
index 67c4039..c10d6f6 100644
--- a/user/exe/debugging.rst
+++ b/user/exe/debugging.rst
@@ -91,7 +91,7 @@ the architecture and processor. Typical functions include:
#. Break and watch points
-.. _fig-exe-debug-qemu:
+.. _fig-exe-debug-jtag:
.. figure:: ../../images/user/exe-debug-jtag.png
:width: 70%
diff --git a/user/exe/index.rst b/user/exe/index.rst
index 02dab19..3e9b571 100644
--- a/user/exe/index.rst
+++ b/user/exe/index.rst
@@ -14,8 +14,10 @@ execute it in a target. The section discusses how an application executable is
created, what happens when an executable is loaded and run, debugging an
execiutable, and creating and dynamically loading code.
-.. include:: executables.rst
-.. include:: execution.rst
-.. include:: initialization.rst
-.. include:: debugging.rst
-.. include:: loader.rst
+.. toctree::
+
+ executables
+ execution
+ initialization
+ debugging
+ loader
diff --git a/user/exe/initialization.rst b/user/exe/initialization.rst
index 4dbfa5c..eb96595 100644
--- a/user/exe/initialization.rst
+++ b/user/exe/initialization.rst
@@ -85,9 +85,11 @@ The RTEMS Tool ``rtems-exeinfo`` can provide some detail about the registered
handlers. The following shows the initialization handlers for the *hello world*
sample application in the RTEMS kernel's testsuite::
+.. code-block:: shell
+
$ rtems-exeinfo --init arm-rtems5/c/xilinx_zynq_zedboard/testsuites/samples/hello.exe
RTEMS Executable Info 5.5416cfa39dd6
- rtems-exeinfo --init arm-rtems5/c/xilinx_zynq_zedboard/testsuites/samples/hello.exe
+ $ rtems-exeinfo --init arm-rtems5/c/xilinx_zynq_zedboard/testsuites/samples/hello.exe
exe: arm-rtems5/c/xilinx_zynq_zedboard/testsuites/samples/hello.exe
Compilation:
diff --git a/user/exe/loader.rst b/user/exe/loader.rst
index 77d7cda..485d691 100644
--- a/user/exe/loader.rst
+++ b/user/exe/loader.rst
@@ -146,6 +146,7 @@ follow.
.. _dlopen:
.. index:: dlopen
+
``void* dlopen(const char* path, int mode);``
The ``dlopen()`` function makes the symbols (function identifiers and data
object identifiers) in the executable object file specified by `file`
@@ -250,6 +251,7 @@ follow.
.. _dlclose:
.. index:: dlclose
+
``int dlclose(void* handle);``
Releases a reference to the executable object file referenced by `handle`. If
the reference count drops to ``0``, the executable object file's global symbol
@@ -262,6 +264,7 @@ follow.
.. _dlsym:
.. index:: dlsym
+
``void* dlsym(void* handle, const char* symbol);``
The ``dlsym()`` function obtains the address of a symbol (a function identifier
or a data object identifier) defined in the symbol table identified by the
@@ -288,6 +291,7 @@ follow.
.. _dlinfo:
.. index:: dlinfo
+
``int dlinfo(void* handle, int request, void* args);``
The ``dlinfo()`` function provides information about dynamically loaded object.
@@ -303,6 +307,7 @@ follow.
.. _dlerror:
.. index:: dlerror
+
``const char *dlerror(void);``
The ``dlerror()`` function returns a null-terminated character string (with no
trailing ``<newline>``) that describes the last error that occurred during
@@ -690,29 +695,35 @@ used to allocate memory at an address must be used when making allocator
calls. The ``rtems_rtl_alloc_tags`` are:
.. index:: RTEMS_RTL_ALLOC_OBJECT
+
``RTEMS_RTL_ALLOC_OBJECT``
Allocate a generic object. The link editor uses this memory for data
structures it uses to manage the linking process and resident executable
object files.
.. index:: RTEMS_RTL_ALLOC_SYMBOL
+
``RTEMS_RTL_ALLOC_SYMBOL``
Allocate memory to hold symbol data.
.. index:: RTEMS_RTL_ALLOC_EXTERNAL
+
``RTEMS_RTL_ALLOC_EXTERNAL``
Allocate memory for unresolved external symbols.
.. index:: RTEMS_RTL_ALLOC_READ
+
``RTEMS_RTL_ALLOC_READ``
Allocate memory for read-only data such as constants and exception tables.
.. index:: RTEMS_RTL_ALLOC_READ_WRITE
+
``RTEMS_RTL_ALLOC_READ_WRITE``
Allocate memory for read-write data such as a initialised, uninitialized and
common variables.
.. index:: RTEMS_RTL_ALLOC_READ_EXEC
+
``RTEMS_RTL_ALLOC_READ_EXEC``
Allocate memory for code to be executed in. The address space is configure for
read and execute.
@@ -724,21 +735,25 @@ The commands are used to control the action the allocator performs. The
``rtems_rtl_alloc_cmd`` are:
.. index:: RTEMS_RTL_ALLOC_NEW
+
``RTEMS_RTL_ALLOC_NEW``
Allocate memory of the ``tag`` type. Returns ``NULL`` if the allocation fails.
.. index:: RTEMS_RTL_ALLOC_DEL
+
``RTEMS_RTL_ALLOC_DEL``
Delete a previous allocation freeing the memory. The ``tag`` has to match
address of the memory being deleted.
.. index:: RTEMS_RTL_ALLOC_WR_ENABLE
+
``RTEMS_RTL_ALLOC_WR_ENABLE``
Enable writes to a region of memory previously allocated. The ``tag`` has to
match the address of the memory being write enabled. The link editor may call
issue this command for memory that is already write enabled.
.. index:: RTEMS_RTL_ALLOC_WR_DISABLE
+
``RTEMS_RTL_ALLOC_WR_DISABLE``
Disable writes to a region of memory previously allocated. The ``tag`` has to
match address of the memory being write disabled. The link editor may call
@@ -763,11 +778,13 @@ the function you need is:
The arguments are:
``cmd``
- The command to action. See :ref:`_rtems_rtl_alloc_cmd`.
+ The command to action. See `rtems_rtl_alloc_cmd <rtems_rtl_alloc_cmd_>`_.
``tag``
- The type of memory the command is for. The ``tag`` must match the address for
- commands other than ``RTEMS_RTL_ALLOC_OBJECT``.
+
+ The type of memory the command is for. The ``tag`` must match the
+ address for commands other than ``RTEMS_RTL_ALLOC_OBJECT``. See
+ `rtems_rtl_alloc_tags <rtems_rtl_alloc_tags_>`_.
``address``
Pointer to the address. This is set of the ``RTEMS_RTL_ALLOC_OBJECT`` command
diff --git a/user/hosts/macos.rst b/user/hosts/macos.rst
index c68e627..d488f20 100644
--- a/user/hosts/macos.rst
+++ b/user/hosts/macos.rst
@@ -2,7 +2,7 @@
.. Copyright (C) 2016 Chris Johns <chrisj at rtems.org>
-.. _macos:
+.. _MacOS:
Apple MacOS
===========
@@ -19,7 +19,6 @@ suitable.
:ref:`QuickStartPrefixes` details using Prefixes to manage the installation.
-MacOS
.. _Mavericks:
Mavericks
@@ -43,5 +42,3 @@ Sierra
~~~~~~
The RSB works on Sierra with the latest Xcode.
-
-
diff --git a/user/hosts/os.rst b/user/hosts/os.rst
index 98fa6af..d1f0834 100644
--- a/user/hosts/os.rst
+++ b/user/hosts/os.rst
@@ -38,7 +38,7 @@ proven over the years to be difficult to manage in production systems.
The RSB assumes your host is set up and the needed packages are installed
and configured to work. If your host has not been set up please refer to
- :ref:`Hosts` and your host's section for packages you need to install.
+ section that covers your host's packages you need to install.
.. topic:: Path to use when building applications:
@@ -80,4 +80,3 @@ proven over the years to be difficult to manage in production systems.
$ git checkout -t origin/4.11
Branches are available for the 4.9, 4.10, and 4.11 versions of RTEMS.
-
diff --git a/user/hosts/posix.rst b/user/hosts/posix.rst
index 2a3e694..24930e7 100644
--- a/user/hosts/posix.rst
+++ b/user/hosts/posix.rst
@@ -53,27 +53,33 @@ been tested and report as working.
ArchLinux
~~~~~~~~~
-The following packages are required on a fresh Archlinux 64bit installation::
+The following packages are required on a fresh Archlinux 64bit installation:
- # pacman -S base-devel gdb xz unzip ncurses git zlib
+.. code-block:: shell
+
+ # pacman -S base-devel gdb xz unzip ncurses git zlib
Archlinux, by default installs ``texinfo-5`` which is incompatible for building
GCC 4.7 tree. You will have to obtain ``texinfo-legacy`` from ``AUR`` and
-provide a manual override::
+provide a manual override:
+
+.. code-block:: shell
- # pacman -R texinfo
- $ yaourt -S texinfo-legacy
- # ln -s /usr/bin/makeinfo-4.13a /usr/bin/makeinfo
+ # pacman -R texinfo
+ $ yaourt -S texinfo-legacy
+ # ln -s /usr/bin/makeinfo-4.13a /usr/bin/makeinfo
.. _CentOS:
CentOS
~~~~~~
-The following packages are required on a minimal CentOS 6.3 64bit installation::
+The following packages are required on a minimal CentOS 6.3 64bit installation:
+
+.. code-block:: shell
- # yum install autoconf automake binutils gcc gcc-c++ gdb make patch \
- bison flex xz unzip ncurses-devel texinfo zlib-devel python-devel git
+ # yum install autoconf automake binutils gcc gcc-c++ gdb make patch \
+ bison flex xz unzip ncurses-devel texinfo zlib-devel python-devel git
The minimal CentOS distribution is a specific DVD that installs a minimal
system. If you use a full system some of these packages may have been
@@ -85,10 +91,12 @@ Fedora
~~~~~~
The RTEMS Source Builder has been tested on Fedora 19 64bit with the following
-packages::
+packages:
- # yum install ncurses-devel python-devel git bison gcc cvs gcc-c++ \
- flex texinfo patch perl-Text-ParseWords zlib-devel
+.. code-block:: shell
+
+ # yum install ncurses-devel python-devel git bison gcc cvs gcc-c++ \
+ flex texinfo patch perl-Text-ParseWords zlib-devel
.. _Raspbian:
@@ -96,10 +104,12 @@ Raspbian
~~~~~~~~
The is the Debian distribution for the Raspberry Pi. The following packages are
-required::
+required:
+
+.. code-block:: shell
- $ sudo apt-get install autoconf automake bison flex binutils gcc g++ gdb \
- texinfo unzip ncurses-dev python-dev git
+ $ sudo apt-get install autoconf automake bison flex binutils gcc g++ gdb \
+ texinfo unzip ncurses-dev python-dev git
It is recommended you get Model B of the Pi with 512M of memory and to mount a
remote disk over the network. The tools can be built on the network disk with a
@@ -112,11 +122,13 @@ Ubuntu
~~~~~~
The latest version is Ubuntu 18.04.1 LTS 64-bit. This section also includes
-Xubuntu. A minimal installation was used and the following packages installed::
+Xubuntu. A minimal installation was used and the following packages installed:
+
+.. code-block:: shell
+
+ $ sudu apt-get build-dep gcc-defaults g++ gdb git unzip pax bison \
+ flex libpython-dev git libncurses5-dev zlib1g-dev
- $ sudu apt-get build-dep gcc-defaults g++ gdb git unzip pax bison \
- flex libpython-dev git libncurses5-dev zlib1g-dev
-
Note that in previous versions of Ubuntu, the package libpython-dev was
python2.7-dev. The name of packages changes over time. You need the
package with Python development libraries for C/C++ programs.
@@ -124,7 +136,7 @@ package with Python development libraries for C/C++ programs.
It is likely necessary that you will have to enable the Ubuntu Source Repositories.
Users have suggested the following web pages which have instructions:
-* https://askubuntu.com/questions/158871/how-do-i-enable-the-source-code-repositories/158872
+* https://askubuntu.com/questions/158871/how-do-i-enable-the-source-code-repositories/158872
* https://askubuntu.com/questions/496549/error-you-must-put-some-source-uris-in-your-sources-list
.. _Linux Mint:
@@ -133,9 +145,11 @@ Linux Mint
~~~~~~~~~~
zlib package is required on Linux Mint. It has a different name (other
-than the usual zlib-dev)::
+than the usual zlib-dev):
+
+.. code-block:: shell
- # sudo apt-get install zlib1g-dev
+ # sudo apt-get install zlib1g-dev
.. _openSUSE:
@@ -151,17 +165,21 @@ FreeBSD
-------
The RTEMS Source Builder has been tested on FreeBSD 9.1, 10.3 and 11 64bit
-version. You need to install some ports. They are::
+version. You need to install some ports. They are:
+
+.. code-block:: shell
- # cd /usr/ports
- # portinstall --batch lang/python27
+ # cd /usr/ports
+ # portinstall --batch lang/python27
If you wish to build Windows (mingw32) tools please install the following
-ports::
+ports:
- # cd /usr/ports
- # portinstall --batch devel/mingw32-binutils devel/mingw32-gcc
- # portinstall --batch devel/mingw32-zlib devel/mingw32-pthreads
+.. code-block:: shell
+
+ # cd /usr/ports
+ # portinstall --batch devel/mingw32-binutils devel/mingw32-gcc
+ # portinstall --batch devel/mingw32-zlib devel/mingw32-pthreads
The +zlip+ and +pthreads+ ports for MinGW32 are used for builiding a Windows
QEMU.
@@ -175,11 +193,10 @@ NetBSD
------
The RTEMS Source Builder has been tested on NetBSD 6.1 i386. Packages to add
-are::
-
- # pkg_add ftp://ftp.netbsd.org/pub/pkgsrc/packages/NetBSD/i386/6.1/devel/gmake-3.82nb7.tgz
- # pkg_add ftp://ftp.netbsd.org/pub/pkgsrc/packages/NetBSD/i386/6.1/devel/bison-2.7.1.tgz
- # pkg_add ftp://ftp.netbsd.org/pub/pkgsrc/packages/NetBSD/i386/6.1/archivers/xz-5.0.4.tgz
+are:
-.. _MacOS:
+.. code-block:: shell
+ # pkg_add ftp://ftp.netbsd.org/pub/pkgsrc/packages/NetBSD/i386/6.1/devel/gmake-3.82nb7.tgz
+ # pkg_add ftp://ftp.netbsd.org/pub/pkgsrc/packages/NetBSD/i386/6.1/devel/bison-2.7.1.tgz
+ # pkg_add ftp://ftp.netbsd.org/pub/pkgsrc/packages/NetBSD/i386/6.1/archivers/xz-5.0.4.tgz
diff --git a/user/hosts/windows.rst b/user/hosts/windows.rst
index bd63fb5..ffd70a0 100644
--- a/user/hosts/windows.rst
+++ b/user/hosts/windows.rst
@@ -38,7 +38,8 @@ overhead is only during the building of the tools and the RTEMS kernel
and if you use a suitable build system that is native to Windows your
application development should be similar to other operating systems.
-Building is known to work on `Windows 7 64bit Professional` and `Windows 10`.
+Building is known to work on `Windows 7 64bit Professional` and
+`Windows 10 64bit`.
.. _windows-path-length:
@@ -222,49 +223,52 @@ result in Cygiwn binaries. With a Canadian cross-compile a Cygwin
cross-compiler is built as well as the MinGW RTEMS cross-compiler. The Cygwin
cross-compiler is required to build the C runtime for the RTEMS target because
we are building under Cygiwn. The build output for an RTEMS 4.10 ARM tool set
-is::
-
- chris at cygthing ~/development/rtems/src/rtems-source-builder/rtems
- $ ../source-builder/sb-set-builder --log=l-arm.txt --prefix=$HOME/development/rtems/4.10 4.10/rtems-arm
- RTEMS Source Builder - Set Builder, v0.2
- Build Set: 4.10/rtems-arm
- config: expat-2.1.0-1.cfg
- package: expat-2.1.0-x86_64-w64-mingw32-1
- building: expat-2.1.0-x86_64-w64-mingw32-1
- reporting: expat-2.1.0-1.cfg -> expat-2.1.0-x86_64-w64-mingw32-1.html
- config: tools/rtems-binutils-2.20.1-1.cfg
- package: arm-rtems4.10-binutils-2.20.1-1 <1>
- building: arm-rtems4.10-binutils-2.20.1-1
- package: (Cxc) arm-rtems4.10-binutils-2.20.1-1 <2>
- building: (Cxc) arm-rtems4.10-binutils-2.20.1-1
- reporting: tools/rtems-binutils-2.20.1-1.cfg ->
- arm-rtems4.10-binutils-2.20.1-1.html
- config: tools/rtems-gcc-4.4.7-newlib-1.18.0-1.cfg
- package: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
- building: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
- package: (Cxc) arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
- building: (Cxc) arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
- reporting: tools/rtems-gcc-4.4.7-newlib-1.18.0-1.cfg ->
- arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1.html
- config: tools/rtems-gdb-7.3.1-1.cfg
- package: arm-rtems4.10-gdb-7.3.1-1
- building: arm-rtems4.10-gdb-7.3.1-1
- reporting: tools/rtems-gdb-7.3.1-1.cfg -> arm-rtems4.10-gdb-7.3.1-1.html
- config: tools/rtems-kernel-4.10.2.cfg
- package: arm-rtems4.10-kernel-4.10.2-1
- building: arm-rtems4.10-kernel-4.10.2-1
- reporting: tools/rtems-kernel-4.10.2.cfg -> arm-rtems4.10-kernel-4.10.2-1.html
- installing: expat-2.1.0-x86_64-w64-mingw32-1 -> /cygdrive/c/Users/chris/development/rtems/4.10
- installing: arm-rtems4.10-binutils-2.20.1-1 -> /cygdrive/c/Users/chris/development/rtems/4.10 <3>
- installing: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1 -> /cygdrive/c/Users/chris/development/rtems/4.10
- installing: arm-rtems4.10-gdb-7.3.1-1 -> /cygdrive/c/Users/chris/development/rtems/4.10
- installing: arm-rtems4.10-kernel-4.10.2-1 -> /cygdrive/c/Users/chris/development/rtems/4.10
- cleaning: expat-2.1.0-x86_64-w64-mingw32-1
- cleaning: arm-rtems4.10-binutils-2.20.1-1
- cleaning: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
- cleaning: arm-rtems4.10-gdb-7.3.1-1
- cleaning: arm-rtems4.10-kernel-4.10.2-1
- Build Set: Time 10:09:42.810547 <4>
+is:
+
+.. code-block:: shell
+
+ chris at cygwin ~/development/rtems/src/rtems-source-builder/rtems
+ $ ../source-builder/sb-set-builder --log=l-arm.txt \
+ --prefix=$HOME/development/rtems/4.10 4.10/rtems-arm
+ RTEMS Source Builder - Set Builder, v0.2
+ Build Set: 4.10/rtems-arm
+ config: expat-2.1.0-1.cfg
+ package: expat-2.1.0-x86_64-w64-mingw32-1
+ building: expat-2.1.0-x86_64-w64-mingw32-1
+ reporting: expat-2.1.0-1.cfg -> expat-2.1.0-x86_64-w64-mingw32-1.html
+ config: tools/rtems-binutils-2.20.1-1.cfg
+ package: arm-rtems4.10-binutils-2.20.1-1 <1>
+ building: arm-rtems4.10-binutils-2.20.1-1
+ package: (Cxc) arm-rtems4.10-binutils-2.20.1-1 <2>
+ building: (Cxc) arm-rtems4.10-binutils-2.20.1-1
+ reporting: tools/rtems-binutils-2.20.1-1.cfg ->
+ arm-rtems4.10-binutils-2.20.1-1.html
+ config: tools/rtems-gcc-4.4.7-newlib-1.18.0-1.cfg
+ package: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
+ building: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
+ package: (Cxc) arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
+ building: (Cxc) arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
+ reporting: tools/rtems-gcc-4.4.7-newlib-1.18.0-1.cfg ->
+ arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1.html
+ config: tools/rtems-gdb-7.3.1-1.cfg
+ package: arm-rtems4.10-gdb-7.3.1-1
+ building: arm-rtems4.10-gdb-7.3.1-1
+ reporting: tools/rtems-gdb-7.3.1-1.cfg -> arm-rtems4.10-gdb-7.3.1-1.html
+ config: tools/rtems-kernel-4.10.2.cfg
+ package: arm-rtems4.10-kernel-4.10.2-1
+ building: arm-rtems4.10-kernel-4.10.2-1
+ reporting: tools/rtems-kernel-4.10.2.cfg -> arm-rtems4.10-kernel-4.10.2-1.html
+ installing: expat-2.1.0-x86_64-w64-mingw32-1 -> /cygdrive/c/Users/chris/development/rtems/4.10
+ installing: arm-rtems4.10-binutils-2.20.1-1 -> /cygdrive/c/Users/chris/development/rtems/4.10 <3>
+ installing: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1 -> /cygdrive/c/Users/chris/development/rtems/4.10
+ installing: arm-rtems4.10-gdb-7.3.1-1 -> /cygdrive/c/Users/chris/development/rtems/4.10
+ installing: arm-rtems4.10-kernel-4.10.2-1 -> /cygdrive/c/Users/chris/development/rtems/4.10
+ cleaning: expat-2.1.0-x86_64-w64-mingw32-1
+ cleaning: arm-rtems4.10-binutils-2.20.1-1
+ cleaning: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
+ cleaning: arm-rtems4.10-gdb-7.3.1-1
+ cleaning: arm-rtems4.10-kernel-4.10.2-1
+ Build Set: Time 10:09:42.810547 <4>
.. topic:: Items:
@@ -289,4 +293,3 @@ is::
cannot be avoided in all cases. Cygwin and it's fork MSYS are fantastic
pieces of software in a difficult environment. I have found building a single
tool tends to work, building all at once is harder.
-
diff --git a/user/installation/kernel.rst b/user/installation/kernel.rst
index 059b4c7..4978d41 100644
--- a/user/installation/kernel.rst
+++ b/user/installation/kernel.rst
@@ -250,9 +250,6 @@ the API headers and architecture specific libraries to a locaiton under the
RTEMS. Do not mix versions of RTEMS under the same `prefix`. Make installs
RTEMS with the following command:
-.. comment: CCJ - this code block for not parse and gives a warning in
- index.rst.
-
.. code-block:: shell
$ make install
@@ -281,8 +278,8 @@ RTEMS with the following command:
make[3]: Nothing to be done for 'install-data-am'.
make[3]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/cpu'
make[2]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/cpu'
- make[1]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/cpu
- ......
+ make[1]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/cpu'
+ ....
make[1]: Leaving directory '/home/chris/development/rtems/kernel/erc32/sparc-rtems5/c'
make[1]: Entering directory '/home/chris/development/rtems/kernel/erc32'
make[2]: Entering directory '/home/chris/development/rtems/kernel/erc32'
diff --git a/user/overview/index.rst b/user/overview/index.rst
index ef23d55..ee7c59b 100644
--- a/user/overview/index.rst
+++ b/user/overview/index.rst
@@ -5,6 +5,8 @@
Introduction
************
+.. _Overview:
+
Overview
========
diff --git a/user/rsb/bug-reporting.rst b/user/rsb/bug-reporting.rst
index b8fcc71..2adf90a 100644
--- a/user/rsb/bug-reporting.rst
+++ b/user/rsb/bug-reporting.rst
@@ -5,7 +5,7 @@
.. _Bugs, Crashes, and Build Failures:
Bugs, Crashes, and Build Failures
-=================================
+---------------------------------
The RTEMS Source Builder is a Python program and every care is taken to test
the code however bugs, crashes, and build failures can and do happen. If you
diff --git a/user/rsb/commands.rst b/user/rsb/commands.rst
index 214607c..80d74a5 100644
--- a/user/rsb/commands.rst
+++ b/user/rsb/commands.rst
@@ -3,12 +3,14 @@
.. Copyright (C) 2012, 2016 Chris Johns <chrisj at rtems.org>
Commands
-========
+--------
Checker (sb-check)
-------------------
+^^^^^^^^^^^^^^^^^^
-This commands checks your system is set up correctly. Most options are ignored::
+This commands checks your system is set up correctly. Most options are ignored:
+
+.. code-block:: shell
$ ../source-builder/sb-check --help
sb-check: [options] [args]
@@ -47,10 +49,12 @@ This commands checks your system is set up correctly. Most options are ignored::
Environment is ok
Defaults (sb-defaults)
-----------------------
+^^^^^^^^^^^^^^^^^^^^^^
This commands outputs and the default macros for your when given no
-arguments. Most options are ignored::
+arguments. Most options are ignored:
+
+.. code-block:: shell
$ ../source-builder/sb-defaults --help
sb-defaults: [options] [args]
@@ -86,9 +90,11 @@ arguments. Most options are ignored::
--regression : Set --no-install, --keep-going and --always-clean
Set Builder (sb-set-builder)
-----------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-This command builds a set::
+This command builds a set:
+
+.. code-block:: shell
$ ../source-builder/sb-set-builder --help
RTEMS Source Builder, an RTEMS Tools Project (c) 2012-2013 Chris Johns
@@ -291,10 +297,12 @@ The ``arguments`` are a list of build sets to build.
``dep[?]` prefix where ``?`` is a number. The files are listed alphabetically.
Set Builder (sb-builder)
-------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^
This command builds a configuration as described in a configuration
-file. Configuration files have the extension of ``.cfg``::
+file. Configuration files have the extension of ``.cfg``:
+
+.. code-block:: shell
$ ./source-builder/sb-builder --help
sb-builder: [options] [args]
diff --git a/user/rsb/configuration.rst b/user/rsb/configuration.rst
index 141fd3b..85e3626 100644
--- a/user/rsb/configuration.rst
+++ b/user/rsb/configuration.rst
@@ -5,7 +5,7 @@
.. _Configuration:
Configuration
-=============
+-------------
The RTEMS Source Builder has two types of configuration data:
@@ -23,9 +23,11 @@ private build configurations and if you run the RTEMS Source Builder command
from that directory your configurations will be used.
The configuration search path is a macro variable and is reference as
-``%{_configdir}``. It's default is defined as::
+``%{_configdir}``. It's default is defined as:
- _configdir : dir optional<2> %{_topdir}/config:%{_sbdir}/config <1>
+.. code-block:: spec
+
+ _configdir : dir optional %{_topdir}/config:%{_sbdir}/config
.. topic:: Items:
@@ -45,7 +47,7 @@ character. Anything after this character on the line is ignored. There is no
block comment.
Source and Patches
-------------------
+^^^^^^^^^^^^^^^^^^
The RTEMS Source Builder provides a flexible way to manage source. Source and
patches are declare in configurations file using the ``source`` and ``patch``
@@ -88,16 +90,16 @@ and start the build process again.
The URL can contain macros. These are expanded before issuing the request to
download the file. The standard GNU GCC compiler source URL is:
-.. code-block:: auto
+.. code-block:: spec
- %source set<1> gcc<2> ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-%{gcc_version}.tar.bz2
+ %source set gcc ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-%{gcc_version}.tar.bz2
.. topic:: Items:
- 1. The ``%source`` command's set command sets the source. The first is set
- and following sets are ignored.
+ 1. The ``%source`` command's ``set`` command sets the source. The
+ first is set and following sets are ignored.
- 2. The source is part of the ``gcc`` group.
+ 2. The source package is part of the ``gcc`` group.
The type of compression is automatically detected from the file extension. The
supported compression formats are:
@@ -132,7 +134,7 @@ If the source URL references the GitHub API server https://api.github.com/ a
tarball of the specified version is download. For example the URL for the
STLINK project on GitHub and version is:
-.. code-block:: auto
+.. code-block:: spec
%define stlink_version 3494c11
%source set stlink https://api.github.com/repos/texane/stlink/texane-stlink-%{stlink_version}.tar.gz
@@ -168,7 +170,7 @@ from the options with ``=``. The options are:
An example is:
-.. code-block:: auto
+.. code-block:: spec
%source set gcc git://gcc.gnu.org/git/gcc.git?branch=gcc-4_7-branch?reset=hard
@@ -205,12 +207,12 @@ delimited by ``?`` and option arguments are delimited from the options with
The following is an example of checking out from a CVS repository:
-.. code-block:: auto
+.. code-block:: spec
%source set newlib cvs://pserver:anoncvs@sourceware.org/cvs/src?module=newlib?src-prefix=src
Macros and Defaults
--------------------
+^^^^^^^^^^^^^^^^^^^
The RTEMS Source Builder uses tables of *macros* read in when the tool
runs. The initial global set of macros is called the *defaults*. These values
@@ -220,17 +222,23 @@ the build hosts.
Build set and configuration files can define new values updating and extending
the global macro table. For example builds are given a release number. This is
-typically a single number at the end of the package name. For example::
+typically a single number at the end of the package name. For example:
+
+.. code-block:: spec
%define release 1
Once defined if can be accessed in a build set or package configuration file
-with::
+with:
+
+.. code-block:: spec
%{release}
The ``sb-defaults`` command lists the defaults for your host. I will not include
-the output of this command because of its size::
+the output of this command because of its size:
+
+.. code-block:: shell
$ ../source-builder/sb-defaults
@@ -248,7 +256,9 @@ read from the defaults macro file called ``defaults.mc`` located in the top
level RTEMS Source Builder command directory. User macros can be read in at
start up by using the ``--macros`` command line option.
-The format for a macro in macro files is::
+The format for a macro in macro files is:
+
+.. code-block:: ini
Name Type Attribute String
@@ -290,7 +300,9 @@ and the ``String`` field is a single or tripled multiline quoted string. The
'String' can contain references to other macros. Macro that loop are not
currently detected and will cause the tool to lock up.
-Maps are declared anywhere in the map using the map directive::
+Maps are declared anywhere in the map using the map directive:
+
+.. code-block:: ini
# Comments
[my-special-map] <1>
@@ -305,7 +317,9 @@ Maps are declared anywhere in the map using the map directive::
Any macro defintions following a map declaration are placed in that map and the
default map is ``global`` when loading a file. Maps are selected in
-configuration files by using the ``%select`` directive::
+configuration files by using the ``%select`` directive:
+
+.. code-block:: spec
%select my-special-map
@@ -320,9 +334,11 @@ files need to add the ``%{_configdir}`` macro to the start of the file.
Macro map files can include other macro map files using the ``%include``
directive. The macro map to build *binutils*, *gcc*, *newlib*, *gdb* and
-RTEMS from version control heads is::
+RTEMS from version control heads is:
+
+.. code-block:: spec
- # <1>
+ #
# Build all tool parts from version control head.
#
%include %{_configdir}/snapshots/binutils-head.mc
@@ -349,7 +365,7 @@ directory. You need to have the environment variable ``HOME`` defined for this
work.
Report Mailing
---------------
+^^^^^^^^^^^^^^
The build reports can be mailed to a specific email address to logging and
monitoring. Mailing requires a number of parameters to function. These are:
@@ -380,7 +396,9 @@ The ``from`` mail address is taken from:
If you have configured an email and name in git it will be used used. If you do
not a check is made for a ``.mailrc`` file. The environment variable ``MAILRC``
is used if present else your home directory is check. If found the file is
-scanned for the ``from`` setting::
+scanned for the ``from`` setting:
+
+.. code-block:: shell
set from="Foo Bar <foo at bar>"
@@ -392,20 +410,24 @@ default is ``localhost``. You can override the default with a personal
or user macro file or via the command line option ``--smtp-host``.
Build Set Files
----------------
+^^^^^^^^^^^^^^^
Build set files lets you list the packages in the build set you are defining
and have a file extension of ``.bset``. Build sets can define macro variables,
inline include other files and reference other build set or package
configuration files.
-Defining macros is performed with the ``%define`` macro::
+Defining macros is performed with the ``%define`` macro:
+
+.. code-block:: spec
%define _target m32r-rtems4.11
Inline including another file with the ``%include`` macro continues processing
with the specified file returning to carry on from just after the include
-point::
+point:
+
+.. code-block:: spec
%include rtems-4.11-base.bset
@@ -413,7 +435,9 @@ This includes the RTEMS 4.11 base set of defines and checks. The configuration
paths as defined by ``_configdir`` are scanned. The file extension is optional.
You reference build set or package configuration files by placing the file name
-on a single line::
+on a single line:
+
+.. code-block:: spec
tools/rtems-binutils-2.22-1
@@ -425,7 +449,7 @@ package configuration the package is built with the package builder. This all
happens once the build set file has finished being scanned.
Configuration Control
----------------------
+^^^^^^^^^^^^^^^^^^^^^
The RTEMS Souce Builder is designed to fit within most verification and
validation processes. All of the RTEMS Source Builder is source code. The
@@ -441,7 +465,9 @@ example the RTEMS configuration file ``rtems-gcc-4.7.2-newlib-2.0.0-1.cfg``
creates an RTEMS GCC and Newlib package where the GCC version is 4.7.2, the
Newlib version is 2.0.0, plus any RTEMS specific patches that related to this
version. The configuration defines the version numbers of the various parts
-that make up this package::
+that make up this package:
+
+.. code-block:: spec
%define gcc_version 4.7.2
%define newlib_version 2.0.0
@@ -449,7 +475,9 @@ that make up this package::
%define mpc_version 0.8.2
%define gmp_version 5.0.5
-The package build options, if there are any are also defined::
+The package build options, if there are any are also defined:
+
+.. code-block:: spec
%define with_threads 1
%define with_plugin 0
@@ -457,11 +485,15 @@ The package build options, if there are any are also defined::
The generic configuration may provide defaults in case options are not
specified. The patches this specific version of the package requires can be
-included::
+included:
+
+.. code-block:: spec
Patch0: gcc-4.7.2-rtems4.11-20121026.diff
-Finally including the GCC 4.7 configuration script::
+Finally including the GCC 4.7 configuration script:
+
+.. code-block:: spec
%include %{_configdir}/gcc-4.7-1.cfg
@@ -476,7 +508,7 @@ the earlier revision number will not be effected by the change. This locks down
a specific configuration over time.
Personal Configurations
------------------------
+^^^^^^^^^^^^^^^^^^^^^^^
The RSB supports personal configurations. You can view the RTEMS support in the
``rtems`` directory as a private configuration tree that resides within the RSB
@@ -484,7 +516,9 @@ source. There is also the ``bare`` set of configurations. You can create your
own configurations away from the RSB source tree yet use all that the RSB
provides.
-To create a private configuration change to a suitable directory::
+To create a private configuration change to a suitable directory:
+
+.. code-block:: shell
$ cd ~/work
$ mkdir test
@@ -496,7 +530,7 @@ build set file. The section 'Adding New Configurations' details how to add a
new confguration.
New Configurations
-------------------
+^^^^^^^^^^^^^^^^^^
This section describes how to add a new configuration to the RSB. We will add a
configuration to build the Device Tree Compiler. The Device Tree Compiler or
@@ -558,7 +592,9 @@ release 1 of the package and the last ``1`` is the build configuration version.
The file starts with some comments that detail the configuration. If there is
anything unusual about the configuration it is a good idea to add something in
the comments here. The comments are followed by a check for the release. In
-this case if a release is not provided a default of 1 is used::
+this case if a release is not provided a default of 1 is used:
+
+.. code-block:: spec
#
# DTC 1.x.x Version 1.
@@ -572,7 +608,9 @@ this case if a release is not provided a default of 1 is used::
The next section defines some information about the package. It does not effect
the build and is used to annotate the reports. It is recommended this
-information is kept updated and accurate::
+information is kept updated and accurate:
+
+.. code-block:: spec
Name: dtc-%{dtc_version}-%{_host}-%{release}
Summary: Device Tree Compiler v%{dtc_version} for target %{_target} on host %{_host}
@@ -586,7 +624,9 @@ single source package and it can be downloaded using the HTTP protocol. The RSB
knows this is GZip'ped tar file. If more than one package is needed, add
them increasing the index. The ``gcc-4.8-1.cfg`` configuration contains
examples of more than one source package as well as conditionally including
-source packages based on the outer configuration options::
+source packages based on the outer configuration options:
+
+.. code-block:: spec
#
# Source
@@ -618,7 +658,9 @@ unsure why something is being done a particular way.
The preparation phase will often include source and patch setup commands. Outer
layers can set the source package and add patches as needed while being able to
use a common recipe for the build. Users can override the standard build and
-supply a custom patch for testing using the user macro command line interface::
+supply a custom patch for testing using the user macro command line interface:
+
+.. code-block:: spec
#
# Prepare the source code.
@@ -644,7 +686,9 @@ running ``make``. Note the use of the RSB macros for commands. In the case of
systems we need to use the BSD make and not the GNU make.
If your package requires a configuration stage you need to run this before the
-make stage. Again the GCC common configuration file provides a detailed example::
+make stage. Again the GCC common configuration file provides a detailed example:
+
+.. code-block:: spec
%build
build_top=$(pwd)
@@ -683,7 +727,9 @@ the RSB to vary specific commands based on the host. This can help on hosts
like Windows where bugs can effect the standard commands such as ``rm``. There
are many many macros to help you. You can find these listed in the
``defaults.mc`` file and in the trace output. If you are new to creating and
-editing configurations learning these can take a little time::
+editing configurations learning these can take a little time:
+
+.. code-block:: spec
%install
build_top=$(pwd)
@@ -701,7 +747,9 @@ for you.
Once we have the configuration files we can execute the build using the
``sb-builder`` command. The command will perform the build and create a tar file
-in the ``tar`` directory::
+in the ``tar`` directory:
+
+.. code-block:: shell
$ ../source-builder/sb-builder --prefix=/usr/local \
--log=log_dtc devel/dtc-1.2.0
@@ -720,7 +768,9 @@ as binutils, GCC and GDB and a build set will build each of these packages and
create a single build set tar file or install the tools on the host into the
prefix path.
-The DTC build set file is called ``dtc.bset`` and contains::
+The DTC build set file is called ``dtc.bset`` and contains:
+
+.. code-block:: spec
#
# Build the DTC.
@@ -730,7 +780,9 @@ The DTC build set file is called ``dtc.bset`` and contains::
devel/dtc-1.2.0.cfg
-To build this you can use something similar to::
+To build this you can use something similar to:
+
+.. code-block:: shell
$ ../source-builder/sb-set-builder --prefix=/usr/local --log=log_dtc \
--trace --bset-tar-file --no-install dtc
@@ -772,7 +824,7 @@ and change directory into them and manually run commands until to figure what
the package requires.
Scripting
----------
+^^^^^^^^^
Configuration files specify how to build a package. Configuration files are
scripts and have a ``.cfg`` file extension. The script format is based loosely
@@ -923,23 +975,24 @@ The +%prep+ macro starts a block that continues until the next block macro. The
*prep* or preparation block defines the setup of the package's source and is a
mix of RTEMS Source Builder macros and shell scripting. The sequence is
typically +%source+ macros for source, +%patch+ macros to patch the source
-mixed with some shell commands to correct any source issues::
+mixed with some shell commands to correct any source issues:
+
+.. code-block:: spec
- <1> <2> <3>
%source setup gcc -q -c -T -n %{name}-%{version}
.. topic:: Items:
- 1. The source group to set up.
+ 1. The source group to set up is ``gcc``.
- 2. The source's name.
+ 2. The source's name is the macro ``%{name}``.
- 3. The version of the source.
+ 3. The version of the source is the macro ``%{version}``.
The source set up are declared with the source ``set`` and ``add`` commands. For
example:
-.. code-block:: auto
+.. code-block:: spec
%source set gdb http://ftp.gnu.org/gnu/gdb/gdb-%{gdb_version}.tar.bz2
@@ -957,7 +1010,7 @@ example GNU's GCC was a few tar files for a while and it is now a single tar
file. Support for multiple source files can be conditionally implemented with
the following scripting:
-.. code-block:: auto
+.. code-block:: spec
%source set gcc ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-code-%{gcc_version}.tar.bz2
%source add gcc ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-g++-%{gcc_version}.tar.bz2
@@ -966,7 +1019,7 @@ the following scripting:
Separate modules use separate source groups. The GNU GCC compiler for RTEMS
uses Newlib, MPFR, MPC, and GMP source packages. You define the source with:
-.. code-block:: auto
+.. code-block:: spec
%source set gcc ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-%{gcc_version}.tar.bz2
%source set newlib ftp://sourceware.org/pub/newlib/newlib-%{newlib_version}.tar.gz
@@ -976,7 +1029,7 @@ uses Newlib, MPFR, MPC, and GMP source packages. You define the source with:
and set up with:
-.. code-block:: auto
+.. code-block:: spec
%source setup gcc -q -n gcc-%{gcc_version}
%source setup newlib -q -D -n newlib-%{newlib_version}
@@ -990,22 +1043,24 @@ applied using the +setup+ command. The +setup+ command takes the default patch
option. You can provide options with each patch by adding them as arguments
before the patch URL. Patches with no options uses the +setup+ default.
-.. code-block:: auto
+.. code-block:: spec
%patch add gdb %{rtems_gdb_patches}/gdb-sim-arange-inline.diff
- %patch add gdb -p0 <1> %{rtems_gdb_patches}/gdb-sim-cgen-inline.diff
+ %patch add gdb -p0 %{rtems_gdb_patches}/gdb-sim-cgen-inline.diff
.. topic:: Items:
- 1. This patch has a custom option.
+ 1. This patch has the custom option of ``-p0``.
-To apply these patches::
+To apply these patches:
- %patch setup gdb -p1 <1>
+.. code-block:: spec
+
+ %patch setup gdb -p1
.. topic:: Items:
- 1. The default options.
+ 1. The default options for ``gdb`` set up.
.. _build:
@@ -1018,22 +1073,24 @@ package. It assumes all source code has been unpacked, patch and adjusted so
the build will succeed.
The following is an example take from the GitHub STLink project. The STLink is
-a JTAG debugging device for the ST ARM family of processors::
+a JTAG debugging device for the ST ARM family of processors:
+
+.. code-block:: spec
%build
- export PATH="%{_bindir}:${PATH}" <1>
+ export PATH="%{_bindir}:${PATH}"
- cd texane-stlink-%{stlink_version} <2>
+ cd texane-stlink-%{stlink_version}
- ./autogen.sh <3>
+ ./autogen.sh
%if "%{_build}" != "%{_host}"
- CFLAGS_FOR_BUILD="-g -O2 -Wall" \ <4>
+ CFLAGS_FOR_BUILD="-g -O2 -Wall" \
%endif
- CPPFLAGS="-I $SB_TMPPREFIX/include/libusb-1.0" \ <5>
+ CPPFLAGS="-I $SB_TMPPREFIX/include/libusb-1.0" \
CFLAGS="$SB_OPT_FLAGS" \
LDFLAGS="-L $SB_TMPPREFIX/lib" \
- ./configure \ <6>
+ ./configure \
--build=%{_build} --host=%{_host} \
--verbose \
--prefix=%{_prefix} --bindir=%{_bindir} \
@@ -1041,36 +1098,41 @@ a JTAG debugging device for the ST ARM family of processors::
--includedir=%{_includedir} --libdir=%{_libdir} \
--mandir=%{_mandir} --infodir=%{_infodir}
- %{__make} %{?_smp_mflags} all <7>
+ %{__make} %{?_smp_mflags} all
cd ..
.. topic:: Items:
- 1. Setup the PATH environment variable. This is not always needed.
+ 1. Set up the PATH environment variable by setting the ``PATH`` environment
+ variable. This is not always needed.
- 2. This package builds in the source tree so enter it.
+ 2. This package builds in the source tree
+ ``texane-stlink-%{stlink_version}`` so enter it before building.
3. The package is actually checked directly out from the github project and
- so it needs its autoconf and automake files generated.
+ so it needs its ``autoconf`` and ``automake`` files generated. Invoke the
+ provided script ``autogen.sh``
- 4. Flags for a cross-compiled build.
+ 4. If the build machine and host are not the same the build is a
+ cross-compile. Update the flags for a cross-compiled build.
- 5. Various settings passed to configure to customise the build. In this
- example an include path is being set to the install point of
- ``libusb``. This package requires ``libusb`` is built before it.
+ 5. The flags set in the environment before ``configure`` are various
+ settings that need to be passed to customise the build. In this example
+ an include path is being set to the install point of ``libusb``. This
+ package requires ``libusb`` is built before it.
6. The ``configure`` command. The RTEMS Source Builder provides all the
needed paths as macro variables. You just need to provide them to
``configure``.
- 7. Running make. Do not use ``make`` directly, use the RTEMS Source Builder's
- defined value. This value is specific to the host. A large number of
- packages need GNU make and on BSD systems this is ``gmake``. You can
- optionally add the SMP flags if the packages build system can handle
- parallel building with multiple jobs. The ``_smp_mflags`` value is
- automatically setup for SMP hosts to match the number of cores the host
- has.
+ 7. Run ``make``. Do not use ``make`` directly, use the RTEMS Source
+ Builder's defined value. This value is specific to the host. A large
+ number of packages need GNU make and on BSD systems this is
+ ``gmake``. You can optionally add the SMP flags if the packages build
+ system can handle parallel building with multiple jobs. The
+ ``_smp_mflags`` value is automatically setup for SMP hosts to match the
+ number of cores the host has.
%install
~~~~~~~~
@@ -1086,7 +1148,9 @@ the macro variable ``__tmpdir``. The RTEMS Source Builder sets up a shell
environment variable called ``SB_BUILD_ROOT`` as the standard install point. Most
packages support adding ``DESTDIR=`` to the ``make install`` command.
-Looking at the same example as in :ref:`build`::
+Looking at the same example as in :ref:`build`:
+
+.. code-block:: spec
%install
export PATH="%{_bindir}:${PATH}" <1>
@@ -1134,7 +1198,9 @@ configuration file that contains the ``%include`` macro.
Including files allow a kind of configuration file reuse. The outer
configuration files provide specific information such as package version
numbers and patches and then include a generic configuration script which
-builds the package::
+builds the package:
+
+.. code-block:: spec
%include %{_configdir}/gcc-4.7-1.cfg
@@ -1152,7 +1218,9 @@ with Newlib configuration the name is typically::
The ``%summary`` is a brief description of the package. It is useful when
reporting. This information is not capture in the package anywhere. For the GCC
-with Newlib configuration the summary is typically::
+with Newlib configuration the summary is typically:
+
+.. code-block:: spec
Summary: GCC v%{gcc_version} and Newlib v%{newlib_version} for target %{_target} on host %{_host}
@@ -1161,7 +1229,9 @@ with Newlib configuration the summary is typically::
The ``%release`` is a packaging number that allows revisions of a package to
happen where no package versions change. This value typically increases when
-the configuration building the package changes::
+the configuration building the package changes:
+
+.. code-block:: spec
%define release 1
@@ -1172,7 +1242,9 @@ The ``%version`` macro sets the version the package. If the package is a single
component it tracks that component's version number. For example in the
``libusb`` configuration the ``%version`` is the same as ``%libusb_version``,
however in a GCC with Newlib configuration there is no single version
-number. In this case the GCC version is used::
+number. In this case the GCC version is used:
+
+.. code-block:: spec
Version: %{gcc_version}
@@ -1206,9 +1278,9 @@ source files to be set up. Subsequent ``set`` commands for the same source
group are ignored. this lets you define the standard source files and override
them for specific releases or snapshots. To set a source file group:
-.. code-block:: auto
+.. code-block:: spec
- %source set gcc <1> ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-%{gcc_version}.tar.bz2
+ %source set gcc ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-%{gcc_version}.tar.bz2
.. topic:: Items:
@@ -1217,12 +1289,14 @@ them for specific releases or snapshots. To set a source file group:
To add another source package to be installed into the same source tree you use
the ``add`` command:
-.. code-block:: auto
+.. code-block:: spec
%source add gcc ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/g++-%{gcc_version}.tar.bz2
The source ``setup`` command can only be issued in the ``%prep:`` section. The
-setup is::
+setup is:
+
+.. code-block:: spec
%source gcc setup -q -T -D -n %{name}-%{version}
@@ -1269,25 +1343,29 @@ control applying a group of patches to a specific source tree.
The ``__patchdir`` path is searched.
-To add a patch::
+To add a patch:
- %patch add gcc <1> gcc-4.7.2-rtems4.11-20121026.diff
- %patch add gcc -p0 <2> gcc-4.7.2-rtems4.11-20121101.diff
+.. code-block:: spec
+
+ %patch add gcc gcc-4.7.2-rtems4.11-20121026.diff
+ %patch add gcc -p0 gcc-4.7.2-rtems4.11-20121101.diff
.. topic:: Items:
1. The patch group is ``gcc``.
- 2. Option for this specific patch.
+ 2. Option ``-p0`` is this specific to this patch.
Placing ``%patch setup`` in the ``%prep`` section will apply the groups
patches::
- %patch setup gcc <1> -p1 <2>
+.. code-block:: spec
+
+ %patch setup gcc -p1
- 1. The patch group.
+ 1. The patch group is ``gcc``.
- 2. The default option used to apply the patch.
+ 2. The default option used to apply the patch is ``-p1``.
%hash
~~~~~
@@ -1303,7 +1381,9 @@ The basename of the file is used as the key for the hash.
The hash algorthim can be ``md5``, ``sha1``, ``sha224``, ``sha256``,
``sha384``, and ``sha512`` and we typically use ``md5``.
-To add a hash::
+To add a hash:
+
+.. code-block:: spec
%hash md5 <1> net-snmp-%{net_snmp_version}.tar.gz <2> 7db683faba037249837b226f64d566d4 <3>
@@ -1351,7 +1431,9 @@ recorded in the build report so they can be traced.
Configurations use different maps so macro overrides can target a specific
package.
-The default map is ``global``::
+The default map is ``global``:
+
+.. code-block:: spec
%select gcc-4.8-snapshot <1>
%define one_plus_one 2 <2>
@@ -1367,7 +1449,9 @@ The default map is ``global``::
~~~~~~~
The ``%define`` macro defines a new macro or updates an existing one. If no
-value is given it is assumed to be ``1``::
+value is given it is assumed to be ``1``:
+
+.. code-block:: spec
%define foo bar
%define one_plus_one 2
@@ -1392,7 +1476,9 @@ The ``%if`` macro starts a conditional logic block that can optionally have a
.. list-table::
* - **%{}**
- - Check the macro is set or *true*, ie non-zero::
+ - Check the macro is set or *true*, ie non-zero:
+
+ .. code-block:: spec
%if ${foo}
%warning The test passes, must not be empty or is non-zero
@@ -1401,7 +1487,9 @@ The ``%if`` macro starts a conditional logic block that can optionally have a
%endif
* - **\!**
- - The *not* operator inverts the test of the macro::
+ - The *not* operator inverts the test of the macro:
+
+ .. code-block:: spec
%if ! ${foo}
%warning The test passes, must be empty or zero
@@ -1410,7 +1498,9 @@ The ``%if`` macro starts a conditional logic block that can optionally have a
%endif
* - **==**
- - The left hand size must equal the right hand side. For example::
+ - The left hand size must equal the right hand side. For example:
+
+ .. code-block:: spec
%define one 1
%if ${one} == 1
@@ -1418,7 +1508,10 @@ The ``%if`` macro starts a conditional logic block that can optionally have a
%else
%error The test fails
%endif
- You can also check to see if a macro is empty::
+
+ You can also check to see if a macro is empty:
+
+ .. code-block:: spec
%if ${nothing} == %{nil}
%warning The test passes
@@ -1426,7 +1519,9 @@ The ``%if`` macro starts a conditional logic block that can optionally have a
%error The test fails
* - **!=**
- - The left hand size does not equal the right hand side. For example::
+ - The left hand size does not equal the right hand side. For example:
+
+ .. code-block:: spec
#
# Check a value not being equal.
@@ -1465,7 +1560,9 @@ The ``%if`` macro starts a conditional logic block that can optionally have a
The ``%ifn`` macro inverts the normal ``%if`` logic. It avoids needing to provide
empty *if* blocks followed by *else* blocks. It is useful when checking if a
-macro is defined::
+macro is defined:
+
+.. code-block:: spec
%ifn %{defined foo}
%define foo bar
diff --git a/user/rsb/cross-canadian-cross.rst b/user/rsb/cross-canadian-cross.rst
index 9c157b3..fc903e4 100644
--- a/user/rsb/cross-canadian-cross.rst
+++ b/user/rsb/cross-canadian-cross.rst
@@ -3,7 +3,7 @@
.. Copyright (C) 2012, 2016 Chris Johns <chrisj at rtems.org>
Cross and Canadian Cross Building
-=================================
+---------------------------------
Cross building and Canadian Cross building is the process of building on one
machine an executable that runs on another machine. An example is building a
@@ -13,21 +13,23 @@ and Canadian cross building.
This sections details how to the RSB to cross and Canadian cross build.
Cross Building
---------------
+^^^^^^^^^^^^^^
Cross building is where the _build_ machine and _host_ are different. The
_build_ machine runs the RSB and the _host_ machine is where the output from
the build runs. An example is building a package such as NTP for RTEMS on your
development machine.
-To build the NTP package for RTEMS you enter the RSB command::
+To build the NTP package for RTEMS you enter the RSB command:
+
+.. code-block:: shell
$ ../source-builder/sb-set-builder \
--log=log_ntp_arm.txt \
- --prefix=$HOME/development/rtems/4.11 \ <1>
- --host=arm-rtems4.11 \ <2>
+ --prefix=$HOME/development/rtems/5 \ <1>
+ --host=arm-rtems5 \ <2>
--with-rtems-bsp=xilinx_zynq_zc706 \ <3>
- 4.11/net/ntp
+ 5/net/ntp
.. topic:: Items:
@@ -45,7 +47,7 @@ To build the NTP package for RTEMS you enter the RSB command::
'bin' directory at the end of the path.
Canadian Cross Building
------------------------
+^^^^^^^^^^^^^^^^^^^^^^^
A Canadian cross builds are where the **build**, **host** and **target**
machines all differ. For example building an RTEMS compiler for an ARM
@@ -81,17 +83,21 @@ does not exist or you cannot access.
To perform a cross build add ``--host=`` to the command line. For example
to build a MinGW tool set on FreeBSD for Windows add ``--host=mingw32``
-if the cross compiler is ``mingw32-gcc``::
+if the cross compiler is ``mingw32-gcc``:
+
+.. code-block:: shell
$ ../source-builder/sb-set-builder --host=mingw32 \
--log=l-mingw32-4.11-sparc.txt \
- --prefix=$HOME/development/rtems/4.11 \
- 4.11/rtems-sparc
+ --prefix=$HOME/development/rtems/5 \
+ 5/rtems-sparc
If you are on a Linux Fedora build host with the MinGW packages installed the
-command line is::
+command line is:
+
+.. code-block:: shell
$ ../source-builder/sb-set-builder --host=i686-w64-mingw32 \
--log=l-mingw32-4.11-sparc.txt \
- --prefix=$HOME/development/rtems/4.11 \
- 4.11/rtems-sparc
+ --prefix=$HOME/development/rtems/5 \
+ 5/rtems-sparc
diff --git a/user/rsb/deployment.rst b/user/rsb/deployment.rst
index 3bb9e0a..c0cd1ce 100644
--- a/user/rsb/deployment.rst
+++ b/user/rsb/deployment.rst
@@ -5,7 +5,7 @@
.. _RSBDeployment:
Building and Deploying Tool Binaries
-====================================
+------------------------------------
If you wish to create and distribute your build or you want to archive a build
you can create a tar file. We term this deploying a build. This is a more
@@ -39,7 +39,9 @@ access only. To install a tar file you have downloaded into your new machine's
$HOME/Downloads/rtems-4.11-sparc-rtems4.11-1.tar.bz2
A build set tar file is created by adding ``--bset-tar-file`` option to the
-``sb-set-builder`` command::
+``sb-set-builder`` command:
+
+.. code-block:: shell
$ ../source-builder/sb-set-builder --log=l-sparc.txt \
--prefix=$HOME/development/rtems/4.11 \
@@ -80,7 +82,9 @@ A build set tar file is created by adding ``--bset-tar-file`` option to the
You can also suppress installing the files using the ``--no-install``
option. This is useful if your prefix is not accessiable, for example when
-building Canadian cross compiled tool sets::
+building Canadian cross compiled tool sets:
+
+.. code-block:: shell
$ ../source-builder/sb-set-builder --log=l-sparc.txt \
--prefix=$HOME/development/rtems/4.11 \
@@ -118,7 +122,9 @@ building Canadian cross compiled tool sets::
A package tar file can be created by adding the ``--pkg-tar-files`` to the
``sb-set-builder`` command. This creates a tar file per package built in the
-build set::
+build set:
+
+.. code-block:: shell
$ ../source-builder/sb-set-builder --log=l-sparc.txt \
--prefix=$HOME/development/rtems/4.11 \
diff --git a/user/rsb/history.rst b/user/rsb/history.rst
index 2bb4324..d295e62 100644
--- a/user/rsb/history.rst
+++ b/user/rsb/history.rst
@@ -4,7 +4,7 @@
History
-=======
+-------
The RTEMS Source Builder is a stand alone tool based on another tool called the
*SpecBuilder* written by Chris Johns. The *SpecBuilder* was written around 2010
diff --git a/user/rsb/index.rst b/user/rsb/index.rst
index 70f578e..d499800 100644
--- a/user/rsb/index.rst
+++ b/user/rsb/index.rst
@@ -7,7 +7,7 @@
.. _RSB:
RTEMS Source Builder
-====================
+********************
The RTEMS Source Builder or RSB is a tool to build packages from source. It is
used by the RTEMS project to build it's compilers and OS. The RSB helps
@@ -45,7 +45,7 @@ The RTEMS Source Builder has been tested on:
.. topic:: Setting up your Host
- :ref:`Hosts` details setting up hosts.
+ See :ref:`QuickStartHost` for details on setting up hosts.
The RTEMS Source Builder has two types of configuration data. The first is the
*build set*. A *build set* describes a collection of packages that define a set
@@ -62,7 +62,7 @@ The RTEMS Source Builder does not interact with any host package management
systems. There is no automatic dependence checking between various packages you
build or packages and software your host system you may have installed. We
assume the build sets and configuration files you are using have been created
-by developers who do. Support is provided for package config or ``pkgconfg``
+by developers who do. Support is provided for package config or ``pkgconfig``
type files so you can check and use standard libraries if present. If you have
a problem please ask on our :r:list:`devel`.
@@ -82,8 +82,6 @@ configuration can read the remaining sections.
Build Failures`.
.. toctree::
- :maxdepth: 5
- :numbered:
why-build-from-source.rst
project-sets
diff --git a/user/rsb/project-sets.rst b/user/rsb/project-sets.rst
index cc63aaa..64a23d4 100644
--- a/user/rsb/project-sets.rst
+++ b/user/rsb/project-sets.rst
@@ -3,7 +3,7 @@
.. Copyright (C) 2012, 2016 Chris Johns <chrisj at rtems.org>
Project Sets
-============
+------------
The RTEMS Source Builder supports project configurations. Project
configurations can be public or private and can be contained in the RTEMS
@@ -36,7 +36,7 @@ are implemented with the configuration scripts. The best way to find what is
available is to grep the configuration files for ``with`` and ``without``.
Bare Metal
-----------
+^^^^^^^^^^
The RSB contains a 'bare' configuration tree and you can use this to add
packages you use on the hosts. For example 'qemu' is supported on a range of
@@ -47,8 +47,10 @@ and run on RTEMS.
The **bare metal** support for GNU Tool chains. An example is the
``lang/gcc491`` build set. You need to provide a target via the command line
``--target`` option and this is in the standard 2 or 3 tuple form. For example
-for an ARM compiler you would use ``arm-eabi`` or ``arm-eabihf`, and for SPARC
-you would use `sparc-elf`::
+for an ARM compiler you would use ``arm-eabi`` or ``arm-eabihf``, and for SPARC
+you would use ``sparc-elf``:
+
+.. code-block:: shell
$ cd rtems-source-builder/bare
$ ../source-builder/sb-set-builder --log=log_arm_eabihf \
@@ -77,7 +79,7 @@ you would use `sparc-elf`::
cleaning: arm-eabihf-gdb-7.7-1
RTEMS
------
+^^^^^
The RTEMS Configurations found in the ``rtems`` directory. The configurations
are grouped by RTEMS version. In RTEMS the tools are specific to a specific
@@ -105,7 +107,9 @@ When building RTEMS within the RTEMS Source Builder it needs a suitable working
prefix in order for them to work. The RTEMS Source Builder installs all
packages only after they have been built so if you host does not have a
recent enough version of ``autoconf`` and ``automake`` you first need to build them
-and install them then build your tool set. The commands are::
+and install them then build your tool set. The commands are:
+
+.. code-block:: shell
$ ../source-builder/sb-set-builder --log=l-4.11-at.txt \
--prefix=$HOME/development/rtems/4.11 4.11/rtems-autotools
@@ -125,7 +129,9 @@ build fails a check.
To build snapshots for testing purposes you use the available macro maps
passing them on the command line using the ``--macros`` option. For RTEMS these
are held in ``config/snapshots`` directory. The following builds *newlib* from
-CVS::
+CVS:
+
+.. code-block:: shell
$ ../source-builder/sb-set-builder --log=l-4.11-sparc.txt \
--prefix=$HOME/development/rtems/4.11 \
@@ -133,7 +139,9 @@ CVS::
4.11/rtems-sparc
and the following uses the version control heads for ``binutils``, ``gcc``,
-``newlib``, ``gdb`` and *RTEMS*::
+``newlib``, ``gdb`` and *RTEMS*:
+
+.. code-block:: shell
$ ../source-builder/sb-set-builder --log=l-heads-sparc.txt \
--prefix=$HOME/development/rtems/4.11-head \
@@ -159,7 +167,7 @@ build sets:
Attempt to build a C++ compiler.
Patches
--------
+^^^^^^^
Packages being built by the RSB need patches from time to time and the RSB
supports patching upstream packages. The patches are held in a seperate
@@ -199,7 +207,9 @@ are provided the patch's setup default options are used.
Patches can be declared in build set up files.
-This examples shows how to declare a patch for gdb in the ``lm32`` architecture::
+This examples shows how to declare a patch for gdb in the ``lm32`` architecture:
+
+.. code-block:: spec
%patch add <1> gdb <2> %{rtems_gdb_patches}/lm32/gdb-sim-lm32uart.diff <3>
@@ -212,7 +222,9 @@ This examples shows how to declare a patch for gdb in the ``lm32`` architecture:
3. The patch's URL. It is downloaded from here.
Patches require a checksum to avoid a warning. The ``%hash`` directive can be
-used to add a checksum for a patch that is used to verify the patch::
+used to add a checksum for a patch that is used to verify the patch:
+
+.. code-block:: spec
%hash md5 <1> gdb-sim-lm32uart.diff <2> 77d070878112783292461bd6e7db17fb <3>
@@ -226,7 +238,9 @@ used to add a checksum for a patch that is used to verify the patch::
The patches are applied when a patch ``setup`` command is issued in the
``%prep:`` section. All patches in the group are applied. To apply the GDB
-patch above use::
+patch above use:
+
+.. code-block:: spec
%patch setup <1> gdb <2> -p1 <3>
@@ -251,7 +265,7 @@ it and add it to the RTEMS Tools git repository. For example, to test a local
patch for newlib, add the following two lines to the .cfg file in
``rtems/config/tools/`` that is included by the bset you use:
-.. code-block:: auto
+.. code-block:: spec
%patch add newlib file://0001-this-is-a-newlib-patch.patch <1>
%hash md5 0001-this-is-a-newlib-patch.diff 77d070878112783292461bd6e7db17fb <2>
diff --git a/user/rsb/third-party-packages.rst b/user/rsb/third-party-packages.rst
index 82be4ff..c02153b 100644
--- a/user/rsb/third-party-packages.rst
+++ b/user/rsb/third-party-packages.rst
@@ -3,7 +3,7 @@
.. Copyright (C) 2012, 2016 Chris Johns <chrisj at rtems.org>
RTEMS Third-Party Packages
-========================
+--------------------------
This section describes how to build and add an RTEMS third-party package to the
RSB.
@@ -21,7 +21,7 @@ in the RTEMS build system. If you have any issues with this support please ask
on the RTEMS developers mailing list.
Vertical Integration
---------------------
+^^^^^^^^^^^^^^^^^^^^
The RSB supports horizontal integration with support for multiple
architectures. Adding packages to the RSB as libraries is vertical
@@ -30,7 +30,7 @@ you build a compiler. The same can be done for third-party libraries, you can
crate build sets that stack library dependences vertically to create a *stack*.
Building
---------
+^^^^^^^^
To build a package you need to have a suitable RTEMS tool chain and RTEMS BSP
installed. The set builder command line requires you provide the tools path,
@@ -56,7 +56,7 @@ To build Net-SNMP the command is:
Build Set: Time 0:01:10.651926
Adding
-------
+^^^^^^
Adding a package requires you first build it manually by downloading the source
for the package and building it for RTEMS using the command line of a standard
@@ -114,7 +114,7 @@ A package requires 3 files to be created:
specific parts. See :ref:`Configuration` for more details.
BSP Support
------------
+^^^^^^^^^^^
The RSB provides support to help build packages for RTEMS. RTEMS applications
can be viewed as statically linked executables operating in a single address
@@ -135,7 +135,9 @@ RTEMS.
The RSB provides the configuration file ``rtems/config/rtems-bsp.cfg`` to
support building third-party packages and you need to include this file in your
RTEMS version specific configuration file. For example the Net-SNMP
-configuration file ``rtems/config/net-mgmt/net-snmp-5.7.2.1-1.cfg``::
+configuration file ``rtems/config/net-mgmt/net-snmp-5.7.2.1-1.cfg``:
+
+.. code-block:: spec
#
# NetSNMP 5.7.2.1
@@ -174,8 +176,8 @@ configuration file ``rtems/config/net-mgmt/net-snmp-5.7.2.1-1.cfg``::
3. The Net-SNMP package's version.
- 4. Add specific CFLAGS to the build process. See the
- ``net-snmp-5.7.2.1-1.cfg`` for details.
+ 4. Add specific ``CFLAGS`` to the build process. See the
+ ``net-snmp-5.7.2.1-1.cfg`` for details.
5. The RTEMS Net-SNMP patch downloaded from the RTEMS Tools git repo.
@@ -184,7 +186,9 @@ configuration file ``rtems/config/net-mgmt/net-snmp-5.7.2.1-1.cfg``::
The RSB RTEMS BSP support file ``rtems/config/rtems-bsp.cfg`` checks to make
sure standard command line options are provided. These include ``--host`` and
``--with-rtems-bsp``. If the ``--with-tools`` command line option is not given
-the ``${_prefix}`` is used::
+the ``${_prefix}`` is used:
+
+.. code-block:: spec
%if %{_host} == %{nil} <1>
%error No RTEMS target specified: --host=host
@@ -217,7 +221,9 @@ the ``${_prefix}`` is used::
RTEMS exports the build flags used in *pkgconfig* (.pc) files and the RSB can
read and manage them even when there is no pkgconfig support installed on your
build machine. Using this support we can obtain a BSP's configuration and set
-some standard macros variables (``rtems/config/rtems-bsp.cfg``)::
+some standard macros variables (``rtems/config/rtems-bsp.cfg``):
+
+.. code-block:: spec
%{pkgconfig prefix %{_prefix}/lib/pkgconfig} <1>
%{pkgconfig crosscompile yes} <2>
@@ -246,7 +252,9 @@ The flags obtain by pkgconfig and given a ``rtems_bsp_`` prefix and we uses thes
to set the RSB host support CFLAGS, LDFLAGS and LIBS flags. When we build a 3rd
party library your host computer is the _build_ machine and RTEMS is the _host_
machine therefore we set the ``host`` variables
-(``rtems/config/rtems-bsp.cfg``)::
+(``rtems/config/rtems-bsp.cfg``):
+
+.. code-block:: spec
%define host_cflags %{rtems_bsp_cflags}
%define host_ldflags %{rtems_bsp_ldflags}
@@ -257,7 +265,9 @@ package. Packages by default consider the ``_prefix`` the base and install
various files under this tree. The package you are building is specific to a
BSP and so needs to install into the specific BSP path under the
``_prefix``. This allows more than BSP build of this package to be install
-under the same ``_prefix`` at the same time (``rtems/config/rtems-bsp.cfg``)::
+under the same ``_prefix`` at the same time (``rtems/config/rtems-bsp.cfg``):
+
+.. code-block:: spec
%define rtems_bsp_prefix %{_prefix}/%{_host}/%{rtems_bsp} <1>
%define _exec_prefix %{rtems_bsp_prefix}
@@ -285,7 +295,9 @@ under the same ``_prefix`` at the same time (``rtems/config/rtems-bsp.cfg``)::
When you configure a package you can reference these paths and the RSB will
provide sensible default or in this case map them to the BSP
-(``source-builder/config/ntp-4-1.cfg``)::
+(``source-builder/config/ntp-4-1.cfg``):
+
+.. code-block:: spec
../${source_dir_ntp}/configure \ <1>
--host=%{_host} \
@@ -306,7 +318,7 @@ provide sensible default or in this case map them to the BSP
1. The configure command for NTP.
RTEMS BSP Configuration
------------------------
+^^^^^^^^^^^^^^^^^^^^^^^
To build a package for RTEMS you need to build it with the matching BSP
configuration. A BSP can be built with specific flags that require all code
diff --git a/user/rsb/why-build-from-source.rst b/user/rsb/why-build-from-source.rst
index d9cdcff..4f1615c 100644
--- a/user/rsb/why-build-from-source.rst
+++ b/user/rsb/why-build-from-source.rst
@@ -5,7 +5,7 @@
.. _WhyBuildFromSource:
Why Build from Source?
-======================
+----------------------
The RTEMS Source Builder is not a replacement for the binary install systems
you have with commercial operating systems or open source operating system
diff --git a/user/start/index.rst b/user/start/index.rst
index d5aa1be..d6333f3 100644
--- a/user/start/index.rst
+++ b/user/start/index.rst
@@ -13,8 +13,6 @@ Follow the sections of this chapter step by step to get started developing
applications on top of RTEMS.
.. toctree::
- :maxdepth: 5
- :numbered:
host
prefixes
diff --git a/user/testing/configuration.rst b/user/testing/configuration.rst
index e740af6..9c65506 100644
--- a/user/testing/configuration.rst
+++ b/user/testing/configuration.rst
@@ -57,6 +57,7 @@ The RTEMS Tester and RTEMS Run are primed using defaults from the file
User configuration file.
.. index:: BSP configuration, User configuration
+
BSP and User Configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -65,18 +66,21 @@ configuration file has to have an INI section that is the name of the BSP
passed on the command line. The section has the following mandatory values:
.. index:: bsp
+
``bsp``
The name of the BSP. The BSP name is used to create a macro map to hold the
BSP's configuration data. Typically this is the same as the BSP name used on
the command line.
.. index:: arch
+
``arch``
The name of the BSP architecture. This is need for the GDB configuration
scripts where the architecture specific GDB needs to run. It is mandatory so
the *arch/bsp* standard RTEMS BSP string can be used.
.. index:: tester
+
``tester``
The tester or run configuration script. This is the name of the configuration
script the RTEMS Tester or RTEMS Run executes as a back end. The ``tester``
@@ -87,18 +91,22 @@ Target commands support expansion of specific tags to provide a convenient way
for users to customize a local test environment. The parameters expanded are:
.. index:: @ARCH@
+
``@ARCH@``
The BSP architecture.
.. index:: @BSP@
+
``@BSP@``
The BSP's name set by the ``bsp`` value.
.. index:: @EXE@
+
``@EXE@``
The executable name as an absolute path
.. index:: @FEXE@
+
``@FEXE@``
The filtered executable if a ``target_exe_filter`` is provided else the
executable's file name.
@@ -107,6 +115,7 @@ The following are optional and depend on the back end being used and the local
target hardware set up:
.. index:: jobs
+
``jobs``
The jobs value sets the number of jobs that can be run at once. This setting
only effects the RTEMS Tester. The tester can run up to the ``jobs`` value of
@@ -116,12 +125,14 @@ target hardware set up:
test timeouts may be recorded.
.. index:: bsp_tty_dev
+
``bsp_tty_dev``
The BSP's tty device. This can be a real device on the host machine the
executable is being run from or it can be a telnet server and port defined
- using the stand host format. See :ref:`tester-consoles` for details.
+ using the stand host format. See :ref:`TesterConsoles` for details.
.. index:: target_pretest_command
+
``target_pretest_command``
The pre-test command is a host shell command that is called before each test
runs. It can be used to construct a suitable environment or image needed by a
@@ -129,12 +140,14 @@ target hardware set up:
and the bootloader specific format is the output.
.. index:: target_posttest_command
+
``target_posttest_command``
The post-test command is a host shell command that is called after each test
has finished. It can be used to destroy any environment or image created by
the pre-test command.
.. index:: target_exe_filter
+
``target_exe_filter``
The target executable filter transforms the executable name into a filtered
executable name. This filter lets the tester or run command track the name of
@@ -147,11 +160,13 @@ target hardware set up:
is no need to escape the text in the second part, it is just plain test.
.. index:: test_restarts
+
``test_restarts``
The number of restarts before the test is considered ``invalid``. Currently
not used.
.. index:: target_reset_regex
+
``target_reset_regex``
The target reset regular expression. This is a `Python regular expression
<https://docs.python.org/2/library/re.html#regular-expression-syntax>`_ used
@@ -161,6 +176,7 @@ target hardware set up:
messages that indicate the boot process as failed.
.. index:: target_start_regex
+
``target_start_regex``
The target start regular expression. This is a Python regular expression to
@@ -169,6 +185,7 @@ target hardware set up:
restart and ends the test with a suitable result.
.. index:: target_on_command
+
``target_on_command``
The target on command is a host shell command that is called before the first
test. This command powers on a target. Targets should be left powered off
@@ -178,11 +195,13 @@ target hardware set up:
command.
.. index:: target_off_command
+
``target_off_command``
The target off command is a host shell command that is called after the last
test powering off the target.
.. index:: target_reset_command
+
``target_reset_command``
The target reset command is a host shell command that is called when the
target needs to be reset. This command can power cycle the target or toggle a
diff --git a/user/testing/consoles.rst b/user/testing/consoles.rst
index ee5126a..28213c1 100644
--- a/user/testing/consoles.rst
+++ b/user/testing/consoles.rst
@@ -2,7 +2,7 @@
.. Copyright (C) 2018 Chris Johns <chrisj at rtems.org>
-.. _tester-consoles:
+.. _TesterConsoles:
Consoles
--------
diff --git a/user/testing/gdb-jtag.rst b/user/testing/gdb-jtag.rst
index 0f91f52..83e950e 100644
--- a/user/testing/gdb-jtag.rst
+++ b/user/testing/gdb-jtag.rst
@@ -20,7 +20,7 @@ JTAG port of a target.
RTEMS Tester using GDB and JTAG
-The :ref:`fig-tester-gdb-jtag` figure shows the structure of RTEMS Testing
+The Figure :ref:`fig-tester-gdb-jtag` shows the structure of RTEMS Testing
using GDB and JTAG. The executables are built and the ``rtems-test`` command is
run from the top of the build directory. The RTEMS Tester executes the BSP
architecture's GDB and expects the user to provide a ``gdb-script`` to connect
diff --git a/user/testing/index.rst b/user/testing/index.rst
index 7eefff1..a938af4 100644
--- a/user/testing/index.rst
+++ b/user/testing/index.rst
@@ -39,9 +39,11 @@ extend the RTEMS kernel's build time and use more disk space but it worth
building and running them. The RTEMS test executables have the ``.exe`` file
extension.
-.. include:: tests.rst
-.. include:: configuration.rst
-.. include:: consoles.rst
-.. include:: simulation.rst
-.. include:: gdb-jtag.rst
-.. include:: tftp.rst
+.. toctree::
+
+ tests
+ configuration
+ consoles
+ simulation
+ gdb-jtag
+ tftp
diff --git a/user/testing/tests.rst b/user/testing/tests.rst
index 37966c7..0b44d05 100644
--- a/user/testing/tests.rst
+++ b/user/testing/tests.rst
@@ -71,15 +71,18 @@ Test States
The tests states are:
.. index:: test state passed
+
``passed``
The test start and end banners have been sent to the console.
.. index:: test state failure
+
``failure``
The test start banner has been sent to the console and no end banner has been
seen when a target restart is detected.
.. index:: test state expected-fail
+
``excepted-fail``
The test is tagged as ``expected-fail`` in the RTEMS sources for this BSP and
outputs the banner ``*** TEST STATE: EXPECTED_FAIL``. The test is known not
@@ -88,6 +91,7 @@ The tests states are:
otherwise it is recorded as *expected-fail*.
.. index:: test state indeterminate
+
``indeterminate``
The test is tagged as ``indeterminate`` in the RTEMS sources for this BSP and
outputs the banner ``*** TEST STATE: INDETERMINATE``. The test may or may not
@@ -95,12 +99,14 @@ The tests states are:
the test run as far as it can and record the result as indeterminate.
.. index:: test state user-input
+
``user-input``
The test is tagged as ``user-input`` in the RTEMS sources and outputs the
banner ``*** TEST STATE: USER_INPUT``. The RTEMS Tester will reset the target
if the target's configuration provides a target reset command.
.. index:: test state benchmark
+
``benchmark``
The test is tagged as ``benchmark`` in the RTEMS sources and outputs the
banner ``*** TEST STATE: BENCHMARK``. Benchmarks can take a while to run and
@@ -108,6 +114,7 @@ The tests states are:
the target if the target's configuration provides a target reset command.
.. index:: test state timeout
+
``timeout``
The test start banner has been sent to the console and no end banner is seen
within the *timeout* period and the target has not restart. A default
@@ -115,6 +122,7 @@ The tests states are:
provide on the RTEMS Tester's command line using the ``--timeout`` option.
.. index:: test state invalid
+
``invalid``
The test did not output a start banner and the RTEMS Tester has detected the
target has restarted. This means the executable did not load correctly, the
@@ -171,38 +179,45 @@ Test Builds
The test reports the build of RTEMS being tested. The build are:
.. index:: build default
+
``default``
The build is the default. No RTEMS configure options have been used.
.. index:: build posix
+
``posix``
The build includes the POSIX API. The RTEMS configure option
``--enable-posix`` has been used. The ``cpuopts.h`` define ``RTEMS_POSIX``
has defined and it true.
.. index:: build smp
+
``smp``
The build is an SMP kernel. The RTEMS configure option ``--enable-smp`` has
been used. The ``cpuopts.h`` define ``RTEMS_SMP`` has defined and it true.
.. index:: build mp
+
``mp``
The build is an MP kernel. The RTEMS configure option
``--enable-multiprocessing`` has been used. The ``cpuopts.h`` define
``RTEMS_MULTIPROCESSING`` has defined and it true.
.. index:: build paravirt
+
``paravirt``
The build is a paravirtualization kernel. The ``cpuopts.h`` define
``RTEMS_PARAVIRT`` has defined and it true.
.. index:: build debug
+
``debug``
The build includes kernel debugging support. The RTEMS configure option
``--enable-debug`` has been used. The ``cpuopts.h`` define ``RTEMS_DEBUG``
has defined and it true.
.. index:: build profiling
+
``profiling``
The build include profiling support. The RTEMS configure option
``--enable-profiling`` has been used. The ``cpuopts.h`` define
diff --git a/user/testing/tftp.rst b/user/testing/tftp.rst
index 1d01673..54b744a 100644
--- a/user/testing/tftp.rst
+++ b/user/testing/tftp.rst
@@ -22,9 +22,10 @@ U-Boot script.
RTEMS Tester using TFTP and U-Boot.
-The :ref:`fig-tester-tftp-u-boot` figure shows the structure and control flow
-of the RTEMS Tester using TFTP and U-boot. The executables are built and the
-``rtems-test`` command is run from the top of the build directory.
+The Figure :ref:`fig-tester-tftp-u-boot` figure shows the structure and
+control flow of the RTEMS Tester using TFTP and U-boot. The executables are
+built and the ``rtems-test`` command is run from the top of the build
+directory.
This test mode can only support a single test job running at once. You cannot
add more test target hardware and run the tests in parallel.
@@ -45,7 +46,7 @@ The RTEMS Tester TFTP and U-Boot method of testing requires:
#. Console interface cable that matches your target's console UART interface.
-#. Telnet terminal server. See :ref:`tester-consoles`.
+#. Telnet terminal server. See :ref:`TesterConsoles`.
The network power or IO switch is a device that can control power or an IO pin
over a network connection using a script-able protocol such as Telnet or
@@ -58,7 +59,9 @@ Obtain a working image of the U-Boot boot loader for your target. We suggest
you follow the instructions for you target.
Configure U-Boot to network boot using the TFTP protocol. This is U-Boot script
-for a Zedboard::
+for a Zedboard:
+
+.. code-block:: shell
loadaddr=0x02000000
uenvcmd=echo Booting RTEMS Zed from net; set autoload no; dhcp; set serverip 10.10.5.2; tftpboot zed/rtems.img; bootm; reset;
@@ -86,7 +89,9 @@ The BSP's configuration file must contain the standard fields:
- ``jobs`` - Must be set to ``1``.
- ``tester`` - Set to ``%{_rtscripts}/tftp.cfg``
-For example the Zedboard's configuration is::
+For example the Zedboard's configuration is:
+
+.. code-block:: ini
[xilinx_zynq_zedboard]
bsp = xilinx_zynq_zedboard
@@ -159,14 +164,18 @@ substituted. The parameters are:
substituted
Some of these field are normally provided by a user's configuration. To do this
-use::
+use:
+
+.. code-block:: shell
requires = bsp_tty_dev, target_on_command, target_off_command, target_reset_command
The ``requires`` value requires the user provide these settings in their
configuration file.
-The Zedboard's configuration file is::
+The Zedboard's configuration file is:
+
+.. code-block:: ini
[xilinx_zynq_zedboard]
bsp = xilinx_zynq_zedboard
@@ -186,7 +195,9 @@ happen if U-Boot cannot detect the PHY device. It also checks if too many DHCP
requests happen and finally a check is made for any timeouts reported by
U-Boot.
-An example of a user configuration for the Zedboard is::
+An example of a user configuration for the Zedboard is:
+
+.. code-block:: ini
[xilinx_zynq_zedboard]
bsp_tty_dev = selserver:12345
diff --git a/user/tracing/captureengine.rst b/user/tracing/captureengine.rst
index fab8bed..d04b8a4 100644
--- a/user/tracing/captureengine.rst
+++ b/user/tracing/captureengine.rst
@@ -98,7 +98,7 @@ traces the context switches between these tasks. ``cwceil`` and ``cwfloor`` are
set to a narrow range of task priorities to avoid creating noise from a large
number of context switches between tasks we are not interested in.
-.. code:: shell
+.. code-block:: shell
*** BEGIN OF TEST CAPTURE ENGINE ***
*** TEST VERSION: 5.0.0.de9b7d712bf5da6593386fd4fbca0d5f8b8431d8
diff --git a/user/tracing/examples.rst b/user/tracing/examples.rst
index d847533..c44daff 100644
--- a/user/tracing/examples.rst
+++ b/user/tracing/examples.rst
@@ -46,7 +46,7 @@ has been stored) run the following commands to generate traces:
BSP is configured with the following command -
-.. code:: shell
+.. code-block:: shell
../rtems/configure --target=sparc-rtems5 --prefix=/development/rtems/5 \
--enable-networking --enable-tests --enable-rtemsbsp=erc32 --enable-cxx
@@ -58,7 +58,7 @@ following commands according to your installation. Also confirm the path of the
fileio's executable and object files in the last line of the command according
to your installation.
-.. code:: shell
+.. code-block:: shell
sparc-rtems5-gcc -Bsparc-rtems5/erc32/lib/ \
-specs bsp_specs -qrtems -mcpu=cypress -O2 -g -ffunction-sections \
@@ -72,7 +72,7 @@ the application. The link command follows the escape sequence "--". "-C" option
denotes the name of the user configuration file and "-W" specifies the name of
the wrapper c file.
-.. code:: shell
+.. code-block:: shell
rtems-tld -C fileio-trace.ini -W fileio-wrapper -- -Bsparc-rtems5/erc32/lib/ \
-specs bsp_specs -qrtems -mcpu=cypress -O2 -g -ffunction-sections \
@@ -88,13 +88,13 @@ display the contents of the trace buffer and save the buffer to disk in the form
of binary files. Use `rtrace -l` to list the availalble options for commands
with `rtrace`.
-.. code:: shell
+.. code-block:: shell
sparc-rtems5-run sparc-rtems5/c/erc32/testsuites/samples/fileio.exe
The output from the above commands will be as follows:
-.. code:: shell
+.. code-block:: shell
*** BEGIN OF TEST FILE I/O ***
*** TEST VERSION: 5.0.0.de9b7d712bf5da6593386fd4fbca0d5f8b8431d8
diff --git a/user/tracing/introduction.rst b/user/tracing/introduction.rst
index d6f249f..a2e635d 100644
--- a/user/tracing/introduction.rst
+++ b/user/tracing/introduction.rst
@@ -2,7 +2,7 @@
.. Copyright (C) 2016 Chris Johns <chrisj at rtems.org>
-.. _introduction:
+.. _IntroductionToTracing:
Introduction to Tracing
***********************
diff --git a/user/tracing/tracelinker.rst b/user/tracing/tracelinker.rst
index 8aad20f..b1e60fd 100644
--- a/user/tracing/tracelinker.rst
+++ b/user/tracing/tracelinker.rst
@@ -92,7 +92,7 @@ used to include other INI files using the include key name. This is shown in the
following example where the values indicate rtems and rtld-base configuration
files:
-.. code-block:: shell
+.. code-block:: ini
include = rtems.ini, rtld-base.ini
@@ -100,7 +100,7 @@ The trace linker also uses values in keys to specify other sections. In this
example the functions name lists `test-trace-funcs` and that section contains a
headers key that further references a section called `test-headers`:
-.. code-block:: shell
+.. code-block:: ini
functions = test-trace-funcs, rtems-api
@@ -143,7 +143,7 @@ following keys:
The tracer section of the file:`test-trace.ini` is shown below with explanatory
comments.
-.. code-block:: shell
+.. code-block:: ini
;
; RTEMS Trace Linker Test Configuration.
@@ -212,7 +212,7 @@ general options section can contain following sets of keys:
The options section of the file: `test-trace.ini` uses two of the aforementioned
keys as shown below:
-.. code-block:: shell
+.. code-block:: ini
;
; Options can be defined here or on the command line.
@@ -250,7 +250,7 @@ The trace section of the file: `test-trace.ini` is shown below. A trace section
can reference other trace sections of a specific type. This allows a trace
sections to build on other trace sections.
-.. code:: shell
+.. code-block:: ini
; User application trace example.
;
@@ -421,7 +421,7 @@ The file: `test-trace.ini` specifies ``printf-generator`` as its generator. This
section can be found in the file: `rtld-print.ini` in the rtems-tools directory
and is shown below:
-.. code:: shell
+.. code:: ini
;
; A printf generator prints to stdout the trace functions.
diff --git a/user/wscript b/user/wscript
index 4063cd4..8dcbfcd 100644
--- a/user/wscript
+++ b/user/wscript
@@ -1,7 +1,13 @@
from common.waf import cmd_configure as configure
-from common.waf import cmd_build as build
+from common.waf import cmd_build as doc_build
from common.waf import cmd_options as options
from common.waf import spell
from common.waf import cmd_spell
from common.waf import linkcheck
from common.waf import cmd_linkcheck
+
+def build(ctx):
+ sources = {
+ 'exclude' : ['apps/index.rst']
+ }
+ doc_build(ctx, sources = sources)
More information about the vc
mailing list