rtems/rtems-docs
1
0
Fork 0
mirror of https://git.rtems.org/rtems-docs/ synced 2025-07-05 14:14:24 +08:00
Code Issues Packages Projects Releases Wiki Activity

user: Remove nit-picky warnings.

Browse Source
This commit is contained in:
Chris Johns 2019-02-21 13:06:58 +11:00
parent 2e6f49f841
commit 2674d6a949
34 changed files with 540 additions and 312 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
user/bsps/bsps-powerpc.rst
View File

@ -94,7 +94,7 @@ Boot via U-Boot
The application executable file (ELF file) must be converted to an U-Boot The application executable file (ELF file) must be converted to an U-Boot
image. Use the following commands: image. Use the following commands:
:: .. code-block:: shell
powerpc-rtems5-objcopy -O binary app.exe app.bin powerpc-rtems5-objcopy -O binary app.exe app.bin
gzip -9 -f -c app.bin > app.bin.gz 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: 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 tftpboot ${loadaddr} app.img && run loadfdt && bootm ${loadaddr} - ${fdt_addr} ; reset

4
user/bsps/bsps-x86_64.rst
View File

@ -49,7 +49,7 @@ Quick instructions (which may fall out of date) are:
Then edit ``Conf/target.txt`` to set: Then edit ``Conf/target.txt`` to set:
:: .. code-block:: ini
ACTIVE_PLATFORM = OvmfPkg/OvmfPkgX64.dsc ACTIVE_PLATFORM = OvmfPkg/OvmfPkgX64.dsc
TARGET = DEBUG TARGET = DEBUG
@ -67,7 +67,7 @@ You can find the ``OVMF.fd`` file like this as well in the edk2 directory:
$ find . -name "*.fd" $ find . -name "*.fd"
./Build/OvmfX64/DEBUG_GCC5/FV/MEMFD.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_CODE.fd
./Build/OvmfX64/DEBUG_GCC5/FV/OVMF_VARS.fd ./Build/OvmfX64/DEBUG_GCC5/FV/OVMF_VARS.fd

2
user/exe/debugging.rst
View File

@ -91,7 +91,7 @@ the architecture and processor. Typical functions include:
#. Break and watch points #. Break and watch points
.. _fig-exe-debug-qemu: .. _fig-exe-debug-jtag:
.. figure:: ../../images/user/exe-debug-jtag.png .. figure:: ../../images/user/exe-debug-jtag.png
:width: 70% :width: 70%

12
user/exe/index.rst
View File

@ -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 created, what happens when an executable is loaded and run, debugging an
execiutable, and creating and dynamically loading code. execiutable, and creating and dynamically loading code.
.. include:: executables.rst .. toctree::
.. include:: execution.rst
.. include:: initialization.rst executables
.. include:: debugging.rst execution
.. include:: loader.rst initialization
debugging
loader

4
user/exe/initialization.rst
View File

@ -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* handlers. The following shows the initialization handlers for the *hello world*
sample application in the RTEMS kernel's testsuite:: 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-exeinfo --init arm-rtems5/c/xilinx_zynq_zedboard/testsuites/samples/hello.exe
RTEMS Executable Info 5.5416cfa39dd6 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 exe: arm-rtems5/c/xilinx_zynq_zedboard/testsuites/samples/hello.exe
Compilation: Compilation:

23
user/exe/loader.rst
View File

@ -146,6 +146,7 @@ follow.
.. _dlopen: .. _dlopen:
.. index:: dlopen .. index:: dlopen
``void* dlopen(const char* path, int mode);`` ``void* dlopen(const char* path, int mode);``
The ``dlopen()`` function makes the symbols (function identifiers and data The ``dlopen()`` function makes the symbols (function identifiers and data
object identifiers) in the executable object file specified by `file` object identifiers) in the executable object file specified by `file`
@ -250,6 +251,7 @@ follow.
.. _dlclose: .. _dlclose:
.. index:: dlclose .. index:: dlclose
``int dlclose(void* handle);`` ``int dlclose(void* handle);``
Releases a reference to the executable object file referenced by `handle`. If 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 the reference count drops to ``0``, the executable object file's global symbol
@ -262,6 +264,7 @@ follow.
.. _dlsym: .. _dlsym:
.. index:: dlsym .. index:: dlsym
``void* dlsym(void* handle, const char* symbol);`` ``void* dlsym(void* handle, const char* symbol);``
The ``dlsym()`` function obtains the address of a symbol (a function identifier 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 or a data object identifier) defined in the symbol table identified by the
@ -288,6 +291,7 @@ follow.
.. _dlinfo: .. _dlinfo:
.. index:: dlinfo .. index:: dlinfo
``int dlinfo(void* handle, int request, void* args);`` ``int dlinfo(void* handle, int request, void* args);``
The ``dlinfo()`` function provides information about dynamically loaded object. The ``dlinfo()`` function provides information about dynamically loaded object.
@ -303,6 +307,7 @@ follow.
.. _dlerror: .. _dlerror:
.. index:: dlerror .. index:: dlerror
``const char *dlerror(void);`` ``const char *dlerror(void);``
The ``dlerror()`` function returns a null-terminated character string (with no The ``dlerror()`` function returns a null-terminated character string (with no
trailing ``<newline>``) that describes the last error that occurred during 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: calls. The ``rtems_rtl_alloc_tags`` are:
.. index:: RTEMS_RTL_ALLOC_OBJECT .. index:: RTEMS_RTL_ALLOC_OBJECT
``RTEMS_RTL_ALLOC_OBJECT`` ``RTEMS_RTL_ALLOC_OBJECT``
Allocate a generic object. The link editor uses this memory for data Allocate a generic object. The link editor uses this memory for data
structures it uses to manage the linking process and resident executable structures it uses to manage the linking process and resident executable
object files. object files.
.. index:: RTEMS_RTL_ALLOC_SYMBOL .. index:: RTEMS_RTL_ALLOC_SYMBOL
``RTEMS_RTL_ALLOC_SYMBOL`` ``RTEMS_RTL_ALLOC_SYMBOL``
Allocate memory to hold symbol data. Allocate memory to hold symbol data.
.. index:: RTEMS_RTL_ALLOC_EXTERNAL .. index:: RTEMS_RTL_ALLOC_EXTERNAL
``RTEMS_RTL_ALLOC_EXTERNAL`` ``RTEMS_RTL_ALLOC_EXTERNAL``
Allocate memory for unresolved external symbols. Allocate memory for unresolved external symbols.
.. index:: RTEMS_RTL_ALLOC_READ .. index:: RTEMS_RTL_ALLOC_READ
``RTEMS_RTL_ALLOC_READ`` ``RTEMS_RTL_ALLOC_READ``
Allocate memory for read-only data such as constants and exception tables. Allocate memory for read-only data such as constants and exception tables.
.. index:: RTEMS_RTL_ALLOC_READ_WRITE .. index:: RTEMS_RTL_ALLOC_READ_WRITE
``RTEMS_RTL_ALLOC_READ_WRITE`` ``RTEMS_RTL_ALLOC_READ_WRITE``
Allocate memory for read-write data such as a initialised, uninitialized and Allocate memory for read-write data such as a initialised, uninitialized and
common variables. common variables.
.. index:: RTEMS_RTL_ALLOC_READ_EXEC .. index:: RTEMS_RTL_ALLOC_READ_EXEC
``RTEMS_RTL_ALLOC_READ_EXEC`` ``RTEMS_RTL_ALLOC_READ_EXEC``
Allocate memory for code to be executed in. The address space is configure for Allocate memory for code to be executed in. The address space is configure for
read and execute. read and execute.
@ -724,21 +735,25 @@ The commands are used to control the action the allocator performs. The
``rtems_rtl_alloc_cmd`` are: ``rtems_rtl_alloc_cmd`` are:
.. index:: RTEMS_RTL_ALLOC_NEW .. index:: RTEMS_RTL_ALLOC_NEW
``RTEMS_RTL_ALLOC_NEW`` ``RTEMS_RTL_ALLOC_NEW``
Allocate memory of the ``tag`` type. Returns ``NULL`` if the allocation fails. Allocate memory of the ``tag`` type. Returns ``NULL`` if the allocation fails.
.. index:: RTEMS_RTL_ALLOC_DEL .. index:: RTEMS_RTL_ALLOC_DEL
``RTEMS_RTL_ALLOC_DEL`` ``RTEMS_RTL_ALLOC_DEL``
Delete a previous allocation freeing the memory. The ``tag`` has to match Delete a previous allocation freeing the memory. The ``tag`` has to match
address of the memory being deleted. address of the memory being deleted.
.. index:: RTEMS_RTL_ALLOC_WR_ENABLE .. index:: RTEMS_RTL_ALLOC_WR_ENABLE
``RTEMS_RTL_ALLOC_WR_ENABLE`` ``RTEMS_RTL_ALLOC_WR_ENABLE``
Enable writes to a region of memory previously allocated. The ``tag`` has to 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 match the address of the memory being write enabled. The link editor may call
issue this command for memory that is already write enabled. issue this command for memory that is already write enabled.
.. index:: RTEMS_RTL_ALLOC_WR_DISABLE .. index:: RTEMS_RTL_ALLOC_WR_DISABLE
``RTEMS_RTL_ALLOC_WR_DISABLE`` ``RTEMS_RTL_ALLOC_WR_DISABLE``
Disable writes to a region of memory previously allocated. The ``tag`` has to 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 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: The arguments are:
``cmd`` ``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`` ``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`` ``address``
Pointer to the address. This is set of the ``RTEMS_RTL_ALLOC_OBJECT`` command Pointer to the address. This is set of the ``RTEMS_RTL_ALLOC_OBJECT`` command

5
user/hosts/macos.rst
View File

@ -2,7 +2,7 @@
.. Copyright (C) 2016 Chris Johns <chrisj@rtems.org> .. Copyright (C) 2016 Chris Johns <chrisj@rtems.org>
.. _macos: .. _MacOS:
Apple MacOS Apple MacOS
=========== ===========
@ -19,7 +19,6 @@ suitable.
:ref:`QuickStartPrefixes` details using Prefixes to manage the installation. :ref:`QuickStartPrefixes` details using Prefixes to manage the installation.
MacOS
.. _Mavericks: .. _Mavericks:
Mavericks Mavericks
@ -43,5 +42,3 @@ Sierra
~~~~~~ ~~~~~~
The RSB works on Sierra with the latest Xcode. The RSB works on Sierra with the latest Xcode.

3
user/hosts/os.rst
View File

@ -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 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 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: .. 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 $ git checkout -t origin/4.11
Branches are available for the 4.9, 4.10, and 4.11 versions of RTEMS. Branches are available for the 4.9, 4.10, and 4.11 versions of RTEMS.

43
user/hosts/posix.rst
View File

@ -53,13 +53,17 @@ been tested and report as working.
ArchLinux ArchLinux
~~~~~~~~~ ~~~~~~~~~
The following packages are required on a fresh Archlinux 64bit installation:: The following packages are required on a fresh Archlinux 64bit installation:
.. code-block:: shell
# pacman -S base-devel gdb xz unzip ncurses git zlib # pacman -S base-devel gdb xz unzip ncurses git zlib
Archlinux, by default installs ``texinfo-5`` which is incompatible for building 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 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 # pacman -R texinfo
$ yaourt -S texinfo-legacy $ yaourt -S texinfo-legacy
@ -70,7 +74,9 @@ provide a manual override::
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 \ # yum install autoconf automake binutils gcc gcc-c++ gdb make patch \
bison flex xz unzip ncurses-devel texinfo zlib-devel python-devel git bison flex xz unzip ncurses-devel texinfo zlib-devel python-devel git
@ -85,7 +91,9 @@ Fedora
~~~~~~ ~~~~~~
The RTEMS Source Builder has been tested on Fedora 19 64bit with the following The RTEMS Source Builder has been tested on Fedora 19 64bit with the following
packages:: packages:
.. code-block:: shell
# yum install ncurses-devel python-devel git bison gcc cvs gcc-c++ \ # yum install ncurses-devel python-devel git bison gcc cvs gcc-c++ \
flex texinfo patch perl-Text-ParseWords zlib-devel flex texinfo patch perl-Text-ParseWords zlib-devel
@ -96,7 +104,9 @@ Raspbian
~~~~~~~~ ~~~~~~~~
The is the Debian distribution for the Raspberry Pi. The following packages are 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 \ $ sudo apt-get install autoconf automake bison flex binutils gcc g++ gdb \
texinfo unzip ncurses-dev python-dev git texinfo unzip ncurses-dev python-dev git
@ -112,7 +122,9 @@ Ubuntu
~~~~~~ ~~~~~~
The latest version is Ubuntu 18.04.1 LTS 64-bit. This section also includes 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 \ $ sudu apt-get build-dep gcc-defaults g++ gdb git unzip pax bison \
flex libpython-dev git libncurses5-dev zlib1g-dev flex libpython-dev git libncurses5-dev zlib1g-dev
@ -133,7 +145,9 @@ Linux Mint
~~~~~~~~~~ ~~~~~~~~~~
zlib package is required on Linux Mint. It has a different name (other 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
@ -151,13 +165,17 @@ FreeBSD
------- -------
The RTEMS Source Builder has been tested on FreeBSD 9.1, 10.3 and 11 64bit 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 # cd /usr/ports
# portinstall --batch lang/python27 # portinstall --batch lang/python27
If you wish to build Windows (mingw32) tools please install the following If you wish to build Windows (mingw32) tools please install the following
ports:: ports:
.. code-block:: shell
# cd /usr/ports # cd /usr/ports
# portinstall --batch devel/mingw32-binutils devel/mingw32-gcc # portinstall --batch devel/mingw32-binutils devel/mingw32-gcc
@ -175,11 +193,10 @@ NetBSD
------ ------
The RTEMS Source Builder has been tested on NetBSD 6.1 i386. Packages to add The RTEMS Source Builder has been tested on NetBSD 6.1 i386. Packages to add
are:: are:
.. 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/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/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 # pkg_add ftp://ftp.netbsd.org/pub/pkgsrc/packages/NetBSD/i386/6.1/archivers/xz-5.0.4.tgz
.. _MacOS:

13
user/hosts/windows.rst
View File

@ -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 and if you use a suitable build system that is native to Windows your
application development should be similar to other operating systems. 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: .. _windows-path-length:
@ -222,10 +223,13 @@ 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 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 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 we are building under Cygiwn. The build output for an RTEMS 4.10 ARM tool set
is:: is:
chris@cygthing ~/development/rtems/src/rtems-source-builder/rtems .. code-block:: shell
$ ../source-builder/sb-set-builder --log=l-arm.txt --prefix=$HOME/development/rtems/4.10 4.10/rtems-arm
chris@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 RTEMS Source Builder - Set Builder, v0.2
Build Set: 4.10/rtems-arm Build Set: 4.10/rtems-arm
config: expat-2.1.0-1.cfg config: expat-2.1.0-1.cfg
@ -289,4 +293,3 @@ is::
cannot be avoided in all cases. Cygwin and it's fork MSYS are fantastic 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 pieces of software in a difficult environment. I have found building a single
tool tends to work, building all at once is harder. tool tends to work, building all at once is harder.

7
user/installation/kernel.rst
View File

@ -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. Do not mix versions of RTEMS under the same `prefix`. Make installs
RTEMS with the following command: RTEMS with the following command:
.. comment: CCJ - this code block for not parse and gives a warning in
index.rst.
.. code-block:: shell .. code-block:: shell
$ make install $ make install
@ -281,8 +278,8 @@ RTEMS with the following command:
make[3]: Nothing to be done for 'install-data-am'. make[3]: Nothing to be done for 'install-data-am'.
make[3]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/cpu' 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[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]: Leaving directory '/home/chris/development/rtems/kernel/erc32/sparc-rtems5/c'
make[1]: Entering directory '/home/chris/development/rtems/kernel/erc32' make[1]: Entering directory '/home/chris/development/rtems/kernel/erc32'
make[2]: Entering directory '/home/chris/development/rtems/kernel/erc32' make[2]: Entering directory '/home/chris/development/rtems/kernel/erc32'

2
user/overview/index.rst
View File

@ -5,6 +5,8 @@
Introduction Introduction
************ ************
.. _Overview:
Overview Overview
======== ========

2
user/rsb/bug-reporting.rst
View File

@ -5,7 +5,7 @@
.. _Bugs, Crashes, and Build Failures: .. _Bugs, Crashes, and Build Failures:
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 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 the code however bugs, crashes, and build failures can and do happen. If you

26
user/rsb/commands.rst
View File

@ -3,12 +3,14 @@
.. Copyright (C) 2012, 2016 Chris Johns <chrisj@rtems.org> .. Copyright (C) 2012, 2016 Chris Johns <chrisj@rtems.org>
Commands Commands
======== --------
Checker (sb-check) 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 $ ../source-builder/sb-check --help
sb-check: [options] [args] sb-check: [options] [args]
@ -47,10 +49,12 @@ This commands checks your system is set up correctly. Most options are ignored::
Environment is ok Environment is ok
Defaults (sb-defaults) Defaults (sb-defaults)
---------------------- ^^^^^^^^^^^^^^^^^^^^^^
This commands outputs and the default macros for your when given no 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 $ ../source-builder/sb-defaults --help
sb-defaults: [options] [args] sb-defaults: [options] [args]
@ -86,9 +90,11 @@ arguments. Most options are ignored::
--regression : Set --no-install, --keep-going and --always-clean --regression : Set --no-install, --keep-going and --always-clean
Set Builder (sb-set-builder) Set Builder (sb-set-builder)
---------------------------- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This command builds a set:: This command builds a set:
.. code-block:: shell
$ ../source-builder/sb-set-builder --help $ ../source-builder/sb-set-builder --help
RTEMS Source Builder, an RTEMS Tools Project (c) 2012-2013 Chris Johns 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. ``dep[?]` prefix where ``?`` is a number. The files are listed alphabetically.
Set Builder (sb-builder) Set Builder (sb-builder)
------------------------ ^^^^^^^^^^^^^^^^^^^^^^^^
This command builds a configuration as described in a configuration 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 $ ./source-builder/sb-builder --help
sb-builder: [options] [args] sb-builder: [options] [args]

311
user/rsb/configuration.rst
View File

@ -5,7 +5,7 @@
.. _Configuration: .. _Configuration:
Configuration Configuration
============= -------------
The RTEMS Source Builder has two types of configuration data: 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. from that directory your configurations will be used.
The configuration search path is a macro variable and is reference as 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: .. topic:: Items:
@ -45,7 +47,7 @@ character. Anything after this character on the line is ignored. There is no
block comment. block comment.
Source and Patches Source and Patches
------------------ ^^^^^^^^^^^^^^^^^^
The RTEMS Source Builder provides a flexible way to manage source. Source and The RTEMS Source Builder provides a flexible way to manage source. Source and
patches are declare in configurations file using the ``source`` and ``patch`` 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 The URL can contain macros. These are expanded before issuing the request to
download the file. The standard GNU GCC compiler source URL is: 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: .. topic:: Items:
1. The ``%source`` command's set command sets the source. The first is set 1. The ``%source`` command's ``set`` command sets the source. The
and following sets are ignored. 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 The type of compression is automatically detected from the file extension. The
supported compression formats are: 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 tarball of the specified version is download. For example the URL for the
STLINK project on GitHub and version is: STLINK project on GitHub and version is:
.. code-block:: auto .. code-block:: spec
%define stlink_version 3494c11 %define stlink_version 3494c11
%source set stlink https://api.github.com/repos/texane/stlink/texane-stlink-%{stlink_version}.tar.gz %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: 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 %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: 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 %source set newlib cvs://pserver:anoncvs@sourceware.org/cvs/src?module=newlib?src-prefix=src
Macros and Defaults Macros and Defaults
------------------- ^^^^^^^^^^^^^^^^^^^
The RTEMS Source Builder uses tables of *macros* read in when the tool 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 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 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 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 %define release 1
Once defined if can be accessed in a build set or package configuration file Once defined if can be accessed in a build set or package configuration file
with:: with:
.. code-block:: spec
%{release} %{release}
The ``sb-defaults`` command lists the defaults for your host. I will not include 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 $ ../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 level RTEMS Source Builder command directory. User macros can be read in at
start up by using the ``--macros`` command line option. 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 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 'String' can contain references to other macros. Macro that loop are not
currently detected and will cause the tool to lock up. 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 # Comments
[my-special-map] <1> [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 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 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 %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`` Macro map files can include other macro map files using the ``%include``
directive. The macro map to build *binutils*, *gcc*, *newlib*, *gdb* and directive. The macro map to build *binutils*, *gcc*, *newlib*, *gdb* and
RTEMS from version control heads is:: RTEMS from version control heads is:
# <1> .. code-block:: spec
#
# Build all tool parts from version control head. # Build all tool parts from version control head.
# #
%include %{_configdir}/snapshots/binutils-head.mc %include %{_configdir}/snapshots/binutils-head.mc
@ -349,7 +365,7 @@ directory. You need to have the environment variable ``HOME`` defined for this
work. work.
Report Mailing Report Mailing
-------------- ^^^^^^^^^^^^^^
The build reports can be mailed to a specific email address to logging and 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: 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 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`` 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 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@bar>" set from="Foo Bar <foo@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``. or user macro file or via the command line option ``--smtp-host``.
Build Set Files Build Set Files
--------------- ^^^^^^^^^^^^^^^
Build set files lets you list the packages in the build set you are defining 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, and have a file extension of ``.bset``. Build sets can define macro variables,
inline include other files and reference other build set or package inline include other files and reference other build set or package
configuration files. 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 %define _target m32r-rtems4.11
Inline including another file with the ``%include`` macro continues processing Inline including another file with the ``%include`` macro continues processing
with the specified file returning to carry on from just after the include with the specified file returning to carry on from just after the include
point:: point:
.. code-block:: spec
%include rtems-4.11-base.bset %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. 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 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 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. happens once the build set file has finished being scanned.
Configuration Control Configuration Control
--------------------- ^^^^^^^^^^^^^^^^^^^^^
The RTEMS Souce Builder is designed to fit within most verification and The RTEMS Souce Builder is designed to fit within most verification and
validation processes. All of the RTEMS Source Builder is source code. The 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 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 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 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 gcc_version 4.7.2
%define newlib_version 2.0.0 %define newlib_version 2.0.0
@ -449,7 +475,9 @@ that make up this package::
%define mpc_version 0.8.2 %define mpc_version 0.8.2
%define gmp_version 5.0.5 %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_threads 1
%define with_plugin 0 %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 The generic configuration may provide defaults in case options are not
specified. The patches this specific version of the package requires can be 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 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 %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. a specific configuration over time.
Personal Configurations Personal Configurations
----------------------- ^^^^^^^^^^^^^^^^^^^^^^^
The RSB supports personal configurations. You can view the RTEMS support in the 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 ``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 own configurations away from the RSB source tree yet use all that the RSB
provides. 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 $ cd ~/work
$ mkdir test $ mkdir test
@ -496,7 +530,7 @@ build set file. The section 'Adding New Configurations' details how to add a
new confguration. new confguration.
New Configurations New Configurations
------------------ ^^^^^^^^^^^^^^^^^^
This section describes how to add a new configuration to the RSB. We will add a 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 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 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 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 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. # 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 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 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} Name: dtc-%{dtc_version}-%{_host}-%{release}
Summary: Device Tree Compiler v%{dtc_version} for target %{_target} on host %{_host} 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 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 them increasing the index. The ``gcc-4.8-1.cfg`` configuration contains
examples of more than one source package as well as conditionally including 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 # 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 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 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 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. # 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. 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 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
build_top=$(pwd) 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 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 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 ``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 %install
build_top=$(pwd) build_top=$(pwd)
@ -701,7 +747,9 @@ for you.
Once we have the configuration files we can execute the build using the 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 ``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 \ $ ../source-builder/sb-builder --prefix=/usr/local \
--log=log_dtc devel/dtc-1.2.0 --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 create a single build set tar file or install the tools on the host into the
prefix path. 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. # Build the DTC.
@ -730,7 +780,9 @@ The DTC build set file is called ``dtc.bset`` and contains::
devel/dtc-1.2.0.cfg 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 \ $ ../source-builder/sb-set-builder --prefix=/usr/local --log=log_dtc \
--trace --bset-tar-file --no-install 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. the package requires.
Scripting Scripting
--------- ^^^^^^^^^
Configuration files specify how to build a package. Configuration files are Configuration files specify how to build a package. Configuration files are
scripts and have a ``.cfg`` file extension. The script format is based loosely 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 *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 mix of RTEMS Source Builder macros and shell scripting. The sequence is
typically +%source+ macros for source, +%patch+ macros to patch the source 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} %source setup gcc -q -c -T -n %{name}-%{version}
.. topic:: Items: .. 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 The source set up are declared with the source ``set`` and ``add`` commands. For
example: example:
.. code-block:: auto .. code-block:: spec
%source set gdb http://ftp.gnu.org/gnu/gdb/gdb-%{gdb_version}.tar.bz2 %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 file. Support for multiple source files can be conditionally implemented with
the following scripting: 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 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 %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 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: 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 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 %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: and set up with:
.. code-block:: auto .. code-block:: spec
%source setup gcc -q -n gcc-%{gcc_version} %source setup gcc -q -n gcc-%{gcc_version}
%source setup newlib -q -D -n newlib-%{newlib_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 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. 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 %{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: .. 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: .. topic:: Items:
1. The default options. 1. The default options for ``gdb`` set up.
.. _build: .. _build:
@ -1018,22 +1073,24 @@ package. It assumes all source code has been unpacked, patch and adjusted so
the build will succeed. the build will succeed.
The following is an example take from the GitHub STLink project. The STLink is 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 %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}" %if "%{_build}" != "%{_host}"
CFLAGS_FOR_BUILD="-g -O2 -Wall" \ <4> CFLAGS_FOR_BUILD="-g -O2 -Wall" \
%endif %endif
CPPFLAGS="-I $SB_TMPPREFIX/include/libusb-1.0" \ <5> CPPFLAGS="-I $SB_TMPPREFIX/include/libusb-1.0" \
CFLAGS="$SB_OPT_FLAGS" \ CFLAGS="$SB_OPT_FLAGS" \
LDFLAGS="-L $SB_TMPPREFIX/lib" \ LDFLAGS="-L $SB_TMPPREFIX/lib" \
./configure \ <6> ./configure \
--build=%{_build} --host=%{_host} \ --build=%{_build} --host=%{_host} \
--verbose \ --verbose \
--prefix=%{_prefix} --bindir=%{_bindir} \ --prefix=%{_prefix} --bindir=%{_bindir} \
@ -1041,36 +1098,41 @@ a JTAG debugging device for the ST ARM family of processors::
--includedir=%{_includedir} --libdir=%{_libdir} \ --includedir=%{_includedir} --libdir=%{_libdir} \
--mandir=%{_mandir} --infodir=%{_infodir} --mandir=%{_mandir} --infodir=%{_infodir}
%{__make} %{?_smp_mflags} all <7> %{__make} %{?_smp_mflags} all
cd .. cd ..
.. topic:: Items: .. 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 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 5. The flags set in the environment before ``configure`` are various
example an include path is being set to the install point of settings that need to be passed to customise the build. In this example
``libusb``. This package requires ``libusb`` is built before it. 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 6. The ``configure`` command. The RTEMS Source Builder provides all the
needed paths as macro variables. You just need to provide them to needed paths as macro variables. You just need to provide them to
``configure``. ``configure``.
7. Running make. Do not use ``make`` directly, use the RTEMS Source Builder's 7. Run ``make``. Do not use ``make`` directly, use the RTEMS Source
defined value. This value is specific to the host. A large number of Builder's defined value. This value is specific to the host. A large
packages need GNU make and on BSD systems this is ``gmake``. You can number of packages need GNU make and on BSD systems this is
optionally add the SMP flags if the packages build system can handle ``gmake``. You can optionally add the SMP flags if the packages build
parallel building with multiple jobs. The ``_smp_mflags`` value is system can handle parallel building with multiple jobs. The
automatically setup for SMP hosts to match the number of cores the host ``_smp_mflags`` value is automatically setup for SMP hosts to match the
has. number of cores the host has.
%install %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 environment variable called ``SB_BUILD_ROOT`` as the standard install point. Most
packages support adding ``DESTDIR=`` to the ``make install`` command. 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 %install
export PATH="%{_bindir}:${PATH}" <1> 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 Including files allow a kind of configuration file reuse. The outer
configuration files provide specific information such as package version configuration files provide specific information such as package version
numbers and patches and then include a generic configuration script which 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 %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 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 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} 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 The ``%release`` is a packaging number that allows revisions of a package to
happen where no package versions change. This value typically increases when 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 %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 component it tracks that component's version number. For example in the
``libusb`` configuration the ``%version`` is the same as ``%libusb_version``, ``libusb`` configuration the ``%version`` is the same as ``%libusb_version``,
however in a GCC with Newlib configuration there is no single 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} 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 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: 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: .. 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 To add another source package to be installed into the same source tree you use
the ``add`` command: 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 %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 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} %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. 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 .. code-block:: spec
%patch add gcc -p0 <2> gcc-4.7.2-rtems4.11-20121101.diff
%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: .. topic:: Items:
1. The patch group is ``gcc``. 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 Placing ``%patch setup`` in the ``%prep`` section will apply the groups
patches:: patches::
%patch setup gcc <1> -p1 <2> .. code-block:: spec
1. The patch group. %patch setup gcc -p1
2. The default option used to apply the patch. 1. The patch group is ``gcc``.
2. The default option used to apply the patch is ``-p1``.
%hash %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``, The hash algorthim can be ``md5``, ``sha1``, ``sha224``, ``sha256``,
``sha384``, and ``sha512`` and we typically use ``md5``. ``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> %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 Configurations use different maps so macro overrides can target a specific
package. package.
The default map is ``global``:: The default map is ``global``:
.. code-block:: spec
%select gcc-4.8-snapshot <1> %select gcc-4.8-snapshot <1>
%define one_plus_one 2 <2> %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 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 foo bar
%define one_plus_one 2 %define one_plus_one 2
@ -1392,7 +1476,9 @@ The ``%if`` macro starts a conditional logic block that can optionally have a
.. list-table:: .. 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} %if ${foo}
%warning The test passes, must not be empty or is non-zero %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 %endif
* - **\!** * - **\!**
- The *not* operator inverts the test of the macro:: - The *not* operator inverts the test of the macro:
.. code-block:: spec
%if ! ${foo} %if ! ${foo}
%warning The test passes, must be empty or zero %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 %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 %define one 1
%if ${one} == 1 %if ${one} == 1
@ -1418,7 +1508,10 @@ The ``%if`` macro starts a conditional logic block that can optionally have a
%else %else
%error The test fails %error The test fails
%endif %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} %if ${nothing} == %{nil}
%warning The test passes %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 %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. # 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 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 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} %ifn %{defined foo}
%define foo bar %define foo bar

32
user/rsb/cross-canadian-cross.rst
View File

@ -3,7 +3,7 @@
.. Copyright (C) 2012, 2016 Chris Johns <chrisj@rtems.org> .. Copyright (C) 2012, 2016 Chris Johns <chrisj@rtems.org>
Cross and Canadian Cross Building Cross and Canadian Cross Building
================================= ---------------------------------
Cross building and Canadian Cross building is the process of building on one 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 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. This sections details how to the RSB to cross and Canadian cross build.
Cross Building Cross Building
-------------- ^^^^^^^^^^^^^^
Cross building is where the _build_ machine and _host_ are different. The 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 _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 the build runs. An example is building a package such as NTP for RTEMS on your
development machine. 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 \ $ ../source-builder/sb-set-builder \
--log=log_ntp_arm.txt \ --log=log_ntp_arm.txt \
--prefix=$HOME/development/rtems/4.11 \ <1> --prefix=$HOME/development/rtems/5 \ <1>
--host=arm-rtems4.11 \ <2> --host=arm-rtems5 \ <2>
--with-rtems-bsp=xilinx_zynq_zc706 \ <3> --with-rtems-bsp=xilinx_zynq_zc706 \ <3>
4.11/net/ntp 5/net/ntp
.. topic:: Items: .. 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. 'bin' directory at the end of the path.
Canadian Cross Building Canadian Cross Building
----------------------- ^^^^^^^^^^^^^^^^^^^^^^^
A Canadian cross builds are where the **build**, **host** and **target** A Canadian cross builds are where the **build**, **host** and **target**
machines all differ. For example building an RTEMS compiler for an ARM 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 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`` 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 \ $ ../source-builder/sb-set-builder --host=mingw32 \
--log=l-mingw32-4.11-sparc.txt \ --log=l-mingw32-4.11-sparc.txt \
--prefix=$HOME/development/rtems/4.11 \ --prefix=$HOME/development/rtems/5 \
4.11/rtems-sparc 5/rtems-sparc
If you are on a Linux Fedora build host with the MinGW packages installed the 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 \ $ ../source-builder/sb-set-builder --host=i686-w64-mingw32 \
--log=l-mingw32-4.11-sparc.txt \ --log=l-mingw32-4.11-sparc.txt \
--prefix=$HOME/development/rtems/4.11 \ --prefix=$HOME/development/rtems/5 \
4.11/rtems-sparc 5/rtems-sparc

14
user/rsb/deployment.rst
View File

@ -5,7 +5,7 @@
.. _RSBDeployment: .. _RSBDeployment:
Building and Deploying Tool Binaries Building and Deploying Tool Binaries
==================================== ------------------------------------
If you wish to create and distribute your build or you want to archive a build 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 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 $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 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 \ $ ../source-builder/sb-set-builder --log=l-sparc.txt \
--prefix=$HOME/development/rtems/4.11 \ --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`` You can also suppress installing the files using the ``--no-install``
option. This is useful if your prefix is not accessiable, for example when 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 \ $ ../source-builder/sb-set-builder --log=l-sparc.txt \
--prefix=$HOME/development/rtems/4.11 \ --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 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 ``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 \ $ ../source-builder/sb-set-builder --log=l-sparc.txt \
--prefix=$HOME/development/rtems/4.11 \ --prefix=$HOME/development/rtems/4.11 \

2
user/rsb/history.rst
View File

@ -4,7 +4,7 @@
History History
======= -------
The RTEMS Source Builder is a stand alone tool based on another tool called the 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 *SpecBuilder* written by Chris Johns. The *SpecBuilder* was written around 2010

8
user/rsb/index.rst
View File

@ -7,7 +7,7 @@
.. _RSB: .. _RSB:
RTEMS Source Builder RTEMS Source Builder
==================== ********************
The RTEMS Source Builder or RSB is a tool to build packages from source. It is 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 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 .. 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 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 *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 systems. There is no automatic dependence checking between various packages you
build or packages and software your host system you may have installed. We 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 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 type files so you can check and use standard libraries if present. If you have
a problem please ask on our :r:list:`devel`. a problem please ask on our :r:list:`devel`.
@ -82,8 +82,6 @@ configuration can read the remaining sections.
Build Failures`. Build Failures`.
.. toctree:: .. toctree::
:maxdepth: 5
:numbered:
why-build-from-source.rst why-build-from-source.rst
project-sets project-sets

40
user/rsb/project-sets.rst
View File

@ -3,7 +3,7 @@
.. Copyright (C) 2012, 2016 Chris Johns <chrisj@rtems.org> .. Copyright (C) 2012, 2016 Chris Johns <chrisj@rtems.org>
Project Sets Project Sets
============ ------------
The RTEMS Source Builder supports project configurations. Project The RTEMS Source Builder supports project configurations. Project
configurations can be public or private and can be contained in the RTEMS 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``. available is to grep the configuration files for ``with`` and ``without``.
Bare Metal Bare Metal
---------- ^^^^^^^^^^
The RSB contains a 'bare' configuration tree and you can use this to add 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 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 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 ``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 ``--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 for an ARM compiler you would use ``arm-eabi`` or ``arm-eabihf``, and for SPARC
you would use `sparc-elf`:: you would use ``sparc-elf``:
.. code-block:: shell
$ cd rtems-source-builder/bare $ cd rtems-source-builder/bare
$ ../source-builder/sb-set-builder --log=log_arm_eabihf \ $ ../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 cleaning: arm-eabihf-gdb-7.7-1
RTEMS RTEMS
----- ^^^^^
The RTEMS Configurations found in the ``rtems`` directory. The configurations The RTEMS Configurations found in the ``rtems`` directory. The configurations
are grouped by RTEMS version. In RTEMS the tools are specific to a specific 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 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 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 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 \ $ ../source-builder/sb-set-builder --log=l-4.11-at.txt \
--prefix=$HOME/development/rtems/4.11 4.11/rtems-autotools --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 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 passing them on the command line using the ``--macros`` option. For RTEMS these
are held in ``config/snapshots`` directory. The following builds *newlib* from 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 \ $ ../source-builder/sb-set-builder --log=l-4.11-sparc.txt \
--prefix=$HOME/development/rtems/4.11 \ --prefix=$HOME/development/rtems/4.11 \
@ -133,7 +139,9 @@ CVS::
4.11/rtems-sparc 4.11/rtems-sparc
and the following uses the version control heads for ``binutils``, ``gcc``, 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 \ $ ../source-builder/sb-set-builder --log=l-heads-sparc.txt \
--prefix=$HOME/development/rtems/4.11-head \ --prefix=$HOME/development/rtems/4.11-head \
@ -159,7 +167,7 @@ build sets:
Attempt to build a C++ compiler. Attempt to build a C++ compiler.
Patches Patches
------- ^^^^^^^
Packages being built by the RSB need patches from time to time and the RSB 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 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. 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> %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. 3. The patch's URL. It is downloaded from here.
Patches require a checksum to avoid a warning. The ``%hash`` directive can be 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> %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 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 ``%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> %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 patch for newlib, add the following two lines to the .cfg file in
``rtems/config/tools/`` that is included by the bset you use: ``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> %patch add newlib file://0001-this-is-a-newlib-patch.patch <1>
%hash md5 0001-this-is-a-newlib-patch.diff 77d070878112783292461bd6e7db17fb <2> %hash md5 0001-this-is-a-newlib-patch.diff 77d070878112783292461bd6e7db17fb <2>

38
user/rsb/third-party-packages.rst
View File

@ -3,7 +3,7 @@
.. Copyright (C) 2012, 2016 Chris Johns <chrisj@rtems.org> .. Copyright (C) 2012, 2016 Chris Johns <chrisj@rtems.org>
RTEMS Third-Party Packages RTEMS Third-Party Packages
======================== --------------------------
This section describes how to build and add an RTEMS third-party package to the This section describes how to build and add an RTEMS third-party package to the
RSB. 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. on the RTEMS developers mailing list.
Vertical Integration Vertical Integration
-------------------- ^^^^^^^^^^^^^^^^^^^^
The RSB supports horizontal integration with support for multiple The RSB supports horizontal integration with support for multiple
architectures. Adding packages to the RSB as libraries is vertical 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*. crate build sets that stack library dependences vertically to create a *stack*.
Building Building
-------- ^^^^^^^^
To build a package you need to have a suitable RTEMS tool chain and RTEMS BSP 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, 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 Build Set: Time 0:01:10.651926
Adding Adding
------ ^^^^^^
Adding a package requires you first build it manually by downloading the source 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 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. specific parts. See :ref:`Configuration` for more details.
BSP Support BSP Support
----------- ^^^^^^^^^^^
The RSB provides support to help build packages for RTEMS. RTEMS applications The RSB provides support to help build packages for RTEMS. RTEMS applications
can be viewed as statically linked executables operating in a single address 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 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 support building third-party packages and you need to include this file in your
RTEMS version specific configuration file. For example the Net-SNMP 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 # NetSNMP 5.7.2.1
@ -174,7 +176,7 @@ configuration file ``rtems/config/net-mgmt/net-snmp-5.7.2.1-1.cfg``::
3. The Net-SNMP package's version. 3. The Net-SNMP package's version.
4. Add specific CFLAGS to the build process. See the 4. Add specific ``CFLAGS`` to the build process. See the
``net-snmp-5.7.2.1-1.cfg`` for details. ``net-snmp-5.7.2.1-1.cfg`` for details.
5. The RTEMS Net-SNMP patch downloaded from the RTEMS Tools git repo. 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 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 sure standard command line options are provided. These include ``--host`` and
``--with-rtems-bsp``. If the ``--with-tools`` command line option is not given ``--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> %if %{_host} == %{nil} <1>
%error No RTEMS target specified: --host=host %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 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 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 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 prefix %{_prefix}/lib/pkgconfig} <1>
%{pkgconfig crosscompile yes} <2> %{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 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_ party library your host computer is the _build_ machine and RTEMS is the _host_
machine therefore we set the ``host`` variables 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_cflags %{rtems_bsp_cflags}
%define host_ldflags %{rtems_bsp_ldflags} %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 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 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 ``_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 rtems_bsp_prefix %{_prefix}/%{_host}/%{rtems_bsp} <1>
%define _exec_prefix %{rtems_bsp_prefix} %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 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 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> ../${source_dir_ntp}/configure \ <1>
--host=%{_host} \ --host=%{_host} \
@ -306,7 +318,7 @@ provide sensible default or in this case map them to the BSP
1. The configure command for NTP. 1. The configure command for NTP.
RTEMS BSP Configuration RTEMS BSP Configuration
----------------------- ^^^^^^^^^^^^^^^^^^^^^^^
To build a package for RTEMS you need to build it with the matching BSP 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 configuration. A BSP can be built with specific flags that require all code

2
user/rsb/why-build-from-source.rst
View File

@ -5,7 +5,7 @@
.. _WhyBuildFromSource: .. _WhyBuildFromSource:
Why Build from Source? Why Build from Source?
====================== ----------------------
The RTEMS Source Builder is not a replacement for the binary install systems The RTEMS Source Builder is not a replacement for the binary install systems
you have with commercial operating systems or open source operating system you have with commercial operating systems or open source operating system

2
user/start/index.rst
View File

@ -13,8 +13,6 @@ Follow the sections of this chapter step by step to get started developing
applications on top of RTEMS. applications on top of RTEMS.
.. toctree:: .. toctree::
:maxdepth: 5
:numbered:
host host
prefixes prefixes

21
user/testing/configuration.rst
View File

@ -57,6 +57,7 @@ The RTEMS Tester and RTEMS Run are primed using defaults from the file
User configuration file. User configuration file.
.. index:: BSP configuration, User configuration .. index:: BSP configuration, User configuration
BSP and 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: passed on the command line. The section has the following mandatory values:
.. index:: bsp .. index:: bsp
``bsp`` ``bsp``
The name of the BSP. The BSP name is used to create a macro map to hold the 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 BSP's configuration data. Typically this is the same as the BSP name used on
the command line. the command line.
.. index:: arch .. index:: arch
``arch`` ``arch``
The name of the BSP architecture. This is need for the GDB configuration 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 scripts where the architecture specific GDB needs to run. It is mandatory so
the *arch/bsp* standard RTEMS BSP string can be used. the *arch/bsp* standard RTEMS BSP string can be used.
.. index:: tester .. index:: tester
``tester`` ``tester``
The tester or run configuration script. This is the name of the configuration 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`` 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: for users to customize a local test environment. The parameters expanded are:
.. index:: @ARCH@ .. index:: @ARCH@
``@ARCH@`` ``@ARCH@``
The BSP architecture. The BSP architecture.
.. index:: @BSP@ .. index:: @BSP@
``@BSP@`` ``@BSP@``
The BSP's name set by the ``bsp`` value. The BSP's name set by the ``bsp`` value.
.. index:: @EXE@ .. index:: @EXE@
``@EXE@`` ``@EXE@``
The executable name as an absolute path The executable name as an absolute path
.. index:: @FEXE@ .. index:: @FEXE@
``@FEXE@`` ``@FEXE@``
The filtered executable if a ``target_exe_filter`` is provided else the The filtered executable if a ``target_exe_filter`` is provided else the
executable's file name. 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: target hardware set up:
.. index:: jobs .. index:: jobs
``jobs`` ``jobs``
The jobs value sets the number of jobs that can be run at once. This setting 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 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. test timeouts may be recorded.
.. index:: bsp_tty_dev .. index:: bsp_tty_dev
``bsp_tty_dev`` ``bsp_tty_dev``
The BSP's tty device. This can be a real device on the host machine the 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 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 .. index:: target_pretest_command
``target_pretest_command`` ``target_pretest_command``
The pre-test command is a host shell command that is called before each test 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 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. and the bootloader specific format is the output.
.. index:: target_posttest_command .. index:: target_posttest_command
``target_posttest_command`` ``target_posttest_command``
The post-test command is a host shell command that is called after each test 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 has finished. It can be used to destroy any environment or image created by
the pre-test command. the pre-test command.
.. index:: target_exe_filter .. index:: target_exe_filter
``target_exe_filter`` ``target_exe_filter``
The target executable filter transforms the executable name into a filtered 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 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. is no need to escape the text in the second part, it is just plain test.
.. index:: test_restarts .. index:: test_restarts
``test_restarts`` ``test_restarts``
The number of restarts before the test is considered ``invalid``. Currently The number of restarts before the test is considered ``invalid``. Currently
not used. not used.
.. index:: target_reset_regex .. index:: target_reset_regex
``target_reset_regex`` ``target_reset_regex``
The target reset regular expression. This is a `Python regular expression The target reset regular expression. This is a `Python regular expression
<https://docs.python.org/2/library/re.html#regular-expression-syntax>`_ used <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. messages that indicate the boot process as failed.
.. index:: target_start_regex .. index:: target_start_regex
``target_start_regex`` ``target_start_regex``
The target start regular expression. This is a Python regular expression to 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. restart and ends the test with a suitable result.
.. index:: target_on_command .. index:: target_on_command
``target_on_command`` ``target_on_command``
The target on command is a host shell command that is called before the first 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 test. This command powers on a target. Targets should be left powered off
@ -178,11 +195,13 @@ target hardware set up:
command. command.
.. index:: target_off_command .. index:: target_off_command
``target_off_command`` ``target_off_command``
The target off command is a host shell command that is called after the last The target off command is a host shell command that is called after the last
test powering off the target. test powering off the target.
.. index:: target_reset_command .. index:: target_reset_command
``target_reset_command`` ``target_reset_command``
The target reset command is a host shell command that is called when the 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 target needs to be reset. This command can power cycle the target or toggle a

2
user/testing/consoles.rst
View File

@ -2,7 +2,7 @@
.. Copyright (C) 2018 Chris Johns <chrisj@rtems.org> .. Copyright (C) 2018 Chris Johns <chrisj@rtems.org>
.. _tester-consoles: .. _TesterConsoles:
Consoles Consoles
-------- --------

2
user/testing/gdb-jtag.rst
View File

@ -20,7 +20,7 @@ JTAG port of a target.
RTEMS Tester using GDB and JTAG 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 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 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 architecture's GDB and expects the user to provide a ``gdb-script`` to connect

14
user/testing/index.rst
View File

@ -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 building and running them. The RTEMS test executables have the ``.exe`` file
extension. extension.
.. include:: tests.rst .. toctree::
.. include:: configuration.rst
.. include:: consoles.rst tests
.. include:: simulation.rst configuration
.. include:: gdb-jtag.rst consoles
.. include:: tftp.rst simulation
gdb-jtag
tftp

15
user/testing/tests.rst
View File

@ -71,15 +71,18 @@ Test States
The tests states are: The tests states are:
.. index:: test state passed .. index:: test state passed
``passed`` ``passed``
The test start and end banners have been sent to the console. The test start and end banners have been sent to the console.
.. index:: test state failure .. index:: test state failure
``failure`` ``failure``
The test start banner has been sent to the console and no end banner has been The test start banner has been sent to the console and no end banner has been
seen when a target restart is detected. seen when a target restart is detected.
.. index:: test state expected-fail .. index:: test state expected-fail
``excepted-fail`` ``excepted-fail``
The test is tagged as ``expected-fail`` in the RTEMS sources for this BSP and 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 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*. otherwise it is recorded as *expected-fail*.
.. index:: test state indeterminate .. index:: test state indeterminate
``indeterminate`` ``indeterminate``
The test is tagged as ``indeterminate`` in the RTEMS sources for this BSP and 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 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. the test run as far as it can and record the result as indeterminate.
.. index:: test state user-input .. index:: test state user-input
``user-input`` ``user-input``
The test is tagged as ``user-input`` in the RTEMS sources and outputs the 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 banner ``*** TEST STATE: USER_INPUT``. The RTEMS Tester will reset the target
if the target's configuration provides a target reset command. if the target's configuration provides a target reset command.
.. index:: test state benchmark .. index:: test state benchmark
``benchmark`` ``benchmark``
The test is tagged as ``benchmark`` in the RTEMS sources and outputs the 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 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. the target if the target's configuration provides a target reset command.
.. index:: test state timeout .. index:: test state timeout
``timeout`` ``timeout``
The test start banner has been sent to the console and no end banner is seen 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 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. provide on the RTEMS Tester's command line using the ``--timeout`` option.
.. index:: test state invalid .. index:: test state invalid
``invalid`` ``invalid``
The test did not output a start banner and the RTEMS Tester has detected the 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 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: The test reports the build of RTEMS being tested. The build are:
.. index:: build default .. index:: build default
``default`` ``default``
The build is the default. No RTEMS configure options have been used. The build is the default. No RTEMS configure options have been used.
.. index:: build posix .. index:: build posix
``posix`` ``posix``
The build includes the POSIX API. The RTEMS configure option The build includes the POSIX API. The RTEMS configure option
``--enable-posix`` has been used. The ``cpuopts.h`` define ``RTEMS_POSIX`` ``--enable-posix`` has been used. The ``cpuopts.h`` define ``RTEMS_POSIX``
has defined and it true. has defined and it true.
.. index:: build smp .. index:: build smp
``smp`` ``smp``
The build is an SMP kernel. The RTEMS configure option ``--enable-smp`` has 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. been used. The ``cpuopts.h`` define ``RTEMS_SMP`` has defined and it true.
.. index:: build mp .. index:: build mp
``mp`` ``mp``
The build is an MP kernel. The RTEMS configure option The build is an MP kernel. The RTEMS configure option
``--enable-multiprocessing`` has been used. The ``cpuopts.h`` define ``--enable-multiprocessing`` has been used. The ``cpuopts.h`` define
``RTEMS_MULTIPROCESSING`` has defined and it true. ``RTEMS_MULTIPROCESSING`` has defined and it true.
.. index:: build paravirt .. index:: build paravirt
``paravirt`` ``paravirt``
The build is a paravirtualization kernel. The ``cpuopts.h`` define The build is a paravirtualization kernel. The ``cpuopts.h`` define
``RTEMS_PARAVIRT`` has defined and it true. ``RTEMS_PARAVIRT`` has defined and it true.
.. index:: build debug .. index:: build debug
``debug`` ``debug``
The build includes kernel debugging support. The RTEMS configure option The build includes kernel debugging support. The RTEMS configure option
``--enable-debug`` has been used. The ``cpuopts.h`` define ``RTEMS_DEBUG`` ``--enable-debug`` has been used. The ``cpuopts.h`` define ``RTEMS_DEBUG``
has defined and it true. has defined and it true.
.. index:: build profiling .. index:: build profiling
``profiling`` ``profiling``
The build include profiling support. The RTEMS configure option The build include profiling support. The RTEMS configure option
``--enable-profiling`` has been used. The ``cpuopts.h`` define ``--enable-profiling`` has been used. The ``cpuopts.h`` define

29
user/testing/tftp.rst
View File

@ -22,9 +22,10 @@ U-Boot script.
RTEMS Tester using TFTP and U-Boot. RTEMS Tester using TFTP and U-Boot.
The :ref:`fig-tester-tftp-u-boot` figure shows the structure and control flow The Figure :ref:`fig-tester-tftp-u-boot` figure shows the structure and
of the RTEMS Tester using TFTP and U-boot. The executables are built and the control flow of the RTEMS Tester using TFTP and U-boot. The executables are
``rtems-test`` command is run from the top of the build directory. 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 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. 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. #. 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 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 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. you follow the instructions for you target.
Configure U-Boot to network boot using the TFTP protocol. This is U-Boot script 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 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; 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``. - ``jobs`` - Must be set to ``1``.
- ``tester`` - Set to ``%{_rtscripts}/tftp.cfg`` - ``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] [xilinx_zynq_zedboard]
bsp = xilinx_zynq_zedboard bsp = xilinx_zynq_zedboard
@ -159,14 +164,18 @@ substituted. The parameters are:
substituted substituted
Some of these field are normally provided by a user's configuration. To do this 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 requires = bsp_tty_dev, target_on_command, target_off_command, target_reset_command
The ``requires`` value requires the user provide these settings in their The ``requires`` value requires the user provide these settings in their
configuration file. configuration file.
The Zedboard's configuration file is:: The Zedboard's configuration file is:
.. code-block:: ini
[xilinx_zynq_zedboard] [xilinx_zynq_zedboard]
bsp = 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 requests happen and finally a check is made for any timeouts reported by
U-Boot. 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] [xilinx_zynq_zedboard]
bsp_tty_dev = selserver:12345 bsp_tty_dev = selserver:12345

2
user/tracing/captureengine.rst
View File

@ -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 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. number of context switches between tasks we are not interested in.
.. code:: shell .. code-block:: shell
*** BEGIN OF TEST CAPTURE ENGINE *** *** BEGIN OF TEST CAPTURE ENGINE ***
*** TEST VERSION: 5.0.0.de9b7d712bf5da6593386fd4fbca0d5f8b8431d8 *** TEST VERSION: 5.0.0.de9b7d712bf5da6593386fd4fbca0d5f8b8431d8

10
user/tracing/examples.rst
View File

@ -46,7 +46,7 @@ has been stored) run the following commands to generate traces:
BSP is configured with the following command - BSP is configured with the following command -
.. code:: shell .. code-block:: shell
../rtems/configure --target=sparc-rtems5 --prefix=/development/rtems/5 \ ../rtems/configure --target=sparc-rtems5 --prefix=/development/rtems/5 \
--enable-networking --enable-tests --enable-rtemsbsp=erc32 --enable-cxx --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 fileio's executable and object files in the last line of the command according
to your installation. to your installation.
.. code:: shell .. code-block:: shell
sparc-rtems5-gcc -Bsparc-rtems5/erc32/lib/ \ sparc-rtems5-gcc -Bsparc-rtems5/erc32/lib/ \
-specs bsp_specs -qrtems -mcpu=cypress -O2 -g -ffunction-sections \ -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 denotes the name of the user configuration file and "-W" specifies the name of
the wrapper c file. the wrapper c file.
.. code:: shell .. code-block:: shell
rtems-tld -C fileio-trace.ini -W fileio-wrapper -- -Bsparc-rtems5/erc32/lib/ \ rtems-tld -C fileio-trace.ini -W fileio-wrapper -- -Bsparc-rtems5/erc32/lib/ \
-specs bsp_specs -qrtems -mcpu=cypress -O2 -g -ffunction-sections \ -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 of binary files. Use `rtrace -l` to list the availalble options for commands
with `rtrace`. with `rtrace`.
.. code:: shell .. code-block:: shell
sparc-rtems5-run sparc-rtems5/c/erc32/testsuites/samples/fileio.exe sparc-rtems5-run sparc-rtems5/c/erc32/testsuites/samples/fileio.exe
The output from the above commands will be as follows: The output from the above commands will be as follows:
.. code:: shell .. code-block:: shell
*** BEGIN OF TEST FILE I/O *** *** BEGIN OF TEST FILE I/O ***
*** TEST VERSION: 5.0.0.de9b7d712bf5da6593386fd4fbca0d5f8b8431d8 *** TEST VERSION: 5.0.0.de9b7d712bf5da6593386fd4fbca0d5f8b8431d8

2
user/tracing/introduction.rst
View File

@ -2,7 +2,7 @@
.. Copyright (C) 2016 Chris Johns <chrisj@rtems.org> .. Copyright (C) 2016 Chris Johns <chrisj@rtems.org>
.. _introduction: .. _IntroductionToTracing:
Introduction to Tracing Introduction to Tracing
*********************** ***********************

12
user/tracing/tracelinker.rst
View File

@ -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 following example where the values indicate rtems and rtld-base configuration
files: files:
.. code-block:: shell .. code-block:: ini
include = rtems.ini, rtld-base.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 example the functions name lists `test-trace-funcs` and that section contains a
headers key that further references a section called `test-headers`: headers key that further references a section called `test-headers`:
.. code-block:: shell .. code-block:: ini
functions = test-trace-funcs, rtems-api 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 The tracer section of the file:`test-trace.ini` is shown below with explanatory
comments. comments.
.. code-block:: shell .. code-block:: ini
; ;
; RTEMS Trace Linker Test Configuration. ; 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 The options section of the file: `test-trace.ini` uses two of the aforementioned
keys as shown below: keys as shown below:
.. code-block:: shell .. code-block:: ini
; ;
; Options can be defined here or on the command line. ; 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 can reference other trace sections of a specific type. This allows a trace
sections to build on other trace sections. sections to build on other trace sections.
.. code:: shell .. code-block:: ini
; User application trace example. ; 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 section can be found in the file: `rtld-print.ini` in the rtems-tools directory
and is shown below: and is shown below:
.. code:: shell .. code:: ini
; ;
; A printf generator prints to stdout the trace functions. ; A printf generator prints to stdout the trace functions.

8
user/wscript
View File

@ -1,7 +1,13 @@
from common.waf import cmd_configure as configure 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 cmd_options as options
from common.waf import spell from common.waf import spell
from common.waf import cmd_spell from common.waf import cmd_spell
from common.waf import linkcheck from common.waf import linkcheck
from common.waf import cmd_linkcheck from common.waf import cmd_linkcheck
def build(ctx):
sources = {
'exclude' : ['apps/index.rst']
}
doc_build(ctx, sources = sources)