rtems/rtems-docs
1
0
Fork 0
mirror of https://git.rtems.org/rtems-docs/ synced 2025-07-02 12:40:43 +08:00
Code Issues Packages Projects Releases Wiki Activity

user/rsb: Update 3rd party package build and add packaging details.

Browse Source
This commit is contained in:
Chris Johns 2019-10-13 19:51:25 +11:00
parent 6185f6e635
commit bb47f890c8
6 changed files with 585 additions and 320 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
user/rsb/configuration.rst
View File

@ -879,13 +879,13 @@ The script language is implemented in terms of macros. The built-in list is:
``%hash``:
Define a checksum for a source or patch file.
``%echo``:
``%{echo message}``:
Print the following string as a message.
``%warning``:
``%{warning message}``:
Print the following string as a warning and continue.
``%error``:
``%{error message}``:
Print the following string as an error and exit.
``%select``:

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

@ -15,21 +15,21 @@ This sections details how to the RSB to cross and Canadian cross build.
Cross Building
^^^^^^^^^^^^^^
Cross building is where the _build_ machine and _host_ are different. The
_build_ machine runs the RSB and the _host_ machine is where the output from
the build runs. An example is building a package such as NTP for RTEMS on your
Cross building is where the *build* machine and *host* are different. The
*build* machine runs the RSB and the *host* machine is where the output from
the build runs. An example is building a package such as Curl for RTEMS on your
development machine.
To build the NTP package for RTEMS you enter the RSB command:
To build the Curl package for RTEMS you enter the RSB command:
.. code-block:: none
$ ../source-builder/sb-set-builder \
--log=log_ntp_arm.txt \
--log=log_curl_arm.txt \
--prefix=$HOME/development/rtems/5 \ <1>
--host=arm-rtems5 \ <2>
--with-rtems-bsp=xilinx_zynq_zc706 \ <3>
5/net/ntp
5/ftp/curl
.. topic:: Items:
@ -42,9 +42,18 @@ To build the NTP package for RTEMS you enter the RSB command:
.. note: Installing Into Different Directories
If you install BSPs into a different path to the prefix use the
``--with-tools`` option to specify the path to the tools. Do not add the
'bin' directory at the end of the path.
If you use a prefix that is different to the path the build RTEMS BSP is
installed under use the ``--with-rtems`` option to specify the top level path
to the RTEMS BSP. Do not add an extra directories to the path,the RSB knows
how to search the path.
If the tools have been installed in a different location to the RTEMS BSP and
the prefix use the ``--with-tools`` option to specift the top level path to
the installed tools Again do not add an extar directory such as ``bin`` as
the RSB knows how to search the supplied tools path.
We recommend you install all thrid party packages using the same prefix.
the RTEM BSP you can use the
Canadian Cross Building
^^^^^^^^^^^^^^^^^^^^^^^

66
user/rsb/index.rst
View File

@ -6,30 +6,47 @@
.. _RSB:
RTEMS Source Builder
********************
Source Builder
**************
The RTEMS Source Builder or RSB is a tool to build packages from source. It is
used by the RTEMS project to build it's compilers and OS. The RSB helps
consolidate the details you need to build a package from source in a controlled
and verifiable way. The tool is aimed at developers of software who use tool
sets for embedded development. The RSB is not limited to building tools just
for RTEMS, you can build bare metal development environments.
The RTEMS Source Builder or RSB is a tool to build packages from source. The
RTEMS project uses it to build it's compilers, tools, kernel and 3rd party
packages. The tool is aimed at developers of software for RTEMS who use tool
sets for embedded development.
The RSB consolidates the details you need to build a package from source in a
controlled and verifiable way. The RSB is not limited to building tools for
RTEMS, you can build bare metal development environments.
.. comment: TBD: The section "Installing and Tar Files" does not exist.
The RSB section of this manual caters for a range of users from new to
experienced RTEMS developers who want to understand the RTEMS Source
Builder. New users who just want to build tools should follow :ref:`QuickStart`
in this manual. Users building a binary tool set for release can read the
"Installing and Tar Files". Users wanting to run and test bleeding edge tools
or packages, or wanting update or extend the RSB's configuration can read the
remaining sections.
Embedded development typically uses cross-compiling tool chains, debuggers, and
debugging aids. Together we call these a **tool set**. The RTEMS Source Builder
is designed to fit this specific niche but is not limited to it. The RSB can be
used outside of the RTEMS project and we welcome this.
The RTEMS Source Builder is typically used to build a set of tools or a **build
set**. A **build set** is a collection of packages and a package is a specific
tool, for example GCC or GDB, or library. The RTEMS Source Builder attempts to
support any host environment that runs Python and you can build the package
on. The RSB is not some sort of magic that can take any piece of source code
and make it build. Someone at some point in time has figured out how to build
that package from source and taught this tool.
The RTEMS Source Builder is typically used to build a set of packages or a
**build set**. A **build set** is a collection of packages and a package is a
specific tool, for example GCC, GDB, or library of code and a single **build
set** can build them all in a single command. The RTEMS Source Builder
attempts to support any host environment that runs Python and you can build
the package on. The RSB is not some sort of magic that can take any piece of
source code and make it build. Someone at some point in time has figured out
how to build that package from source and taught this tool.
The RTEMS Source Builder has been tested on:
.. sidebar:: Setting up your Host
See :ref:`QuickStartHost` for details on setting up hosts.
The RTEMS Source Builder is known to work on:
- ArchLinux
- CentOS
@ -40,19 +57,16 @@ The RTEMS Source Builder has been tested on:
- openSUSE
- FreeBSD
- NetBSD
- Solaris
- MacOS
- Windows
.. topic:: Setting up your Host
See :ref:`QuickStartHost` for details on setting up hosts.
The RTEMS Source Builder has two types of configuration data. The first is the
*build set*. A *build set* describes a collection of packages that define a set
of tools you would use when developing software for RTEMS. For example the
basic GNU tool set is Binutils, GCC, and GDB and is the typical base suite of
tools you need for an embedded cross-development type project. The second type
of configuration data is the configuration files and they define how a package
of configuration data are the configuration files and they define how a package
is built. Configuration files are scripts loosely based on the RPM spec file
format and they detail the steps needed to build a package. The steps are
*preparation*, *building*, and *installing*. Scripts support macros, shell
@ -66,16 +80,6 @@ by developers who do. Support is provided for package config or ``pkgconfig``
type files so you can check and use standard libraries if present. If you have
a problem please ask on our :r:list:`devel`.
.. comment: TBD: The section "Installing and Tar Files" does not exist.
This documentation caters for a range of users from new to experienced RTEMS
developers who want to understand the RTEMS Source Builder. New users
who just want to build tools should follow the Quick Start section in
the User's Guide. Users building a binary tool set for release can
read the "Installing and Tar Files". Users wanting to run and test
bleeding edge tools or packages, or wanting update or extend the RSB's
configuration can read the remaining sections.
.. topic:: Bug Reporting
If you think you have found a problem please see :ref:`Bugs, Crashes, and

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

@ -7,22 +7,21 @@ Project Sets
The RTEMS Source Builder supports project configurations. Project
configurations can be public or private and can be contained in the RTEMS
Source Builder project if suitable, other projects they use the RTEMS Source
Builder or privately on your local file system.
Source Builder project if suitable.
The configuration file loader searches the macro ``_configdir`` and by default
this is set to ``%{_topdir}/config:%{_sbdir}/config`` where ``_topdir`` is the
your current working direct, in other words the directory you invoke the RTEMS
Source Builder command in, and ``_sbdir`` is the directory where the RTEMS
Source Builder command resides. Therefore the ``config`` directory under each
of these is searched so all you need to do is create a ``config`` in your
project and add your configuration files. They do not need to be under the
RTEMS Source Builder source tree. Public projects are included in the main
RTEMS Source Builder such as RTEMS.
this is set to ``%{_topdir}/config:%{_sbdir}/config`` where ``_topdir`` is your
current working directory, or the directory you invoke the RTEMS Source Builder
command in. The macro ``_sbdir`` is the directory where the RTEMS Source
Builder command resides. Therefore the ``config`` directory under each of these
is searched so all you need to do is create a ``config`` in your project and
add your configuration files. They do not need to be under the RTEMS Source
Builder source tree. Public projects are included in the main RTEMS Source
Builder such as RTEMS.
You can also add your own ``patches`` directory next to your ``config``
directory as the ``%patch`` command searches the ``_patchdir`` macro variable
and it is by default set to ``%{_topdir}/patches:%{_sbdir}/patches``.
You can add your own ``patches`` directory next to your ``config`` directory as
the ``%patch`` command searches the ``_patchdir`` macro variable and it is by
default set to ``%{_topdir}/patches:%{_sbdir}/patches``.
The ``source-builder/config`` directory provides generic scripts for building
various tools. You can specialise these in your private configurations to make
@ -38,7 +37,7 @@ available is to grep the configuration files for ``with`` and ``without``.
Bare Metal
^^^^^^^^^^
The RSB contains a 'bare' configuration tree and you can use this to add
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
hosts. RTEMS tools live in the ``rtems/config`` directory tree. RTEMS packages
include tools for use on your host computer as well as packages you can build
@ -81,79 +80,30 @@ you would use ``sparc-elf``:
RTEMS
^^^^^
The RTEMS Configurations found in the ``rtems`` directory. The configurations
are grouped by RTEMS version. In RTEMS the tools are specific to a specific
version because of variations between Newlib and RTEMS. Restructuring in RTEMS
and Newlib sometimes moves *libc* functionality between these two parts and
this makes existing tools incompatible with RTEMS.
The RTEMS Configurations are found in the ``rtems`` directory. The
configurations are grouped by RTEMS version and a release normally only
contains the configurations for that release.. In RTEMS the tools are specific
to a specific version because of variations between Newlib and
RTEMS. Restructuring in RTEMS and Newlib sometimes moves *libc* functionality
between these two parts and this makes existing tools incompatible with RTEMS.
RTEMS allows architectures to have different tool versions and patches. The
large number of architectures RTEMS supports can make it difficult to get a
common stable version of all the packages. An architecture may require a recent
GCC because an existing bug has been fixed, however the more recent version may
have a bug in other architecture. Architecture specific patches should be
limited to the architecture it relates to. The patch may fix a problem on the
effect architecture however it could introduce a problem in another
architecture. Limit exposure limits any possible crosstalk between
have a bug in other architecture. Architecture specific patches should only be
appliaed when build the related architecture. A patch may fix a problem on one
architecture however it could introduce a problem in another
architecture. Limiting exposure limits any possible crosstalk between
architectures.
If you are building a released version of RTEMS the release RTEMS tar file will
be downloaded and built as part of the build process. If you are building a
tool set for use with the development branch of RTEMS, the development branch
will be cloned directly from the RTEMS GIT repository and built.
When building RTEMS within the RTEMS Source Builder it needs a suitable working
``autoconf`` and ``automake``. These packages need to built and installed in their
prefix in order for them to work. The RTEMS Source Builder installs all
packages only after they have been built so if you host does not have a
recent enough version of ``autoconf`` and ``automake`` you first need to build them
and install them then build your tool set. The commands are:
.. code-block:: none
$ ../source-builder/sb-set-builder --log=l-4.11-at.txt \
--prefix=$HOME/development/rtems/4.11 4.11/rtems-autotools
$ export PATH=~/development/rtems/4.11/bin:$PATH <1>
$ ../source-builder/sb-set-builder --log=l-4.11-sparc.txt \
--prefix=$HOME/development/rtems/4.11 4.11/rtems-sparc
.. topic:: Items:
1. Setting the path.
If this is your first time building the tools and RTEMS it pays to add the
``--dry-run`` option. This will run through all the configuration files and if
any checks fail you will see this quickly rather than waiting for until the
build fails a check.
To build snapshots for testing purposes you use the available macro maps
passing them on the command line using the ``--macros`` option. For RTEMS these
are held in ``config/snapshots`` directory. The following builds *newlib* from
CVS:
.. code-block:: none
$ ../source-builder/sb-set-builder --log=l-4.11-sparc.txt \
--prefix=$HOME/development/rtems/4.11 \
--macros=snapshots/newlib-head.mc \
4.11/rtems-sparc
and the following uses the version control heads for ``binutils``, ``gcc``,
``newlib``, ``gdb`` and *RTEMS*:
.. code-block:: none
$ ../source-builder/sb-set-builder --log=l-heads-sparc.txt \
--prefix=$HOME/development/rtems/4.11-head \
--macros=snapshots/binutils-gcc-newlib-gdb-head.mc \
4.11/rtems-sparc
If you have a configuation issue try adding the ``--dry-run`` option. This will
run through all the configuration files and if any checks fail you will see
this quickly rather than waiting for until the build fails a check.
Following features can be enabled/disabled via the command line for the RTEMS
build sets:
``--without-rtems``
Do not build RTEMS when building an RTEMS build set.
``--without-cxx``
Do not build a C++ compiler.
@ -166,6 +116,16 @@ build sets:
``--with-objc``
Attempt to build a C++ compiler.
The RSB provides build sets for some BSPs. These build sets will build:
- Compiler, linker, debugger and RTEMS Tools.
- RTEMS Kernel for the BSP
- Optionally LibBSD if supported by the BSP.
- Third party packages if supported by the BSP.
Patches
^^^^^^^
@ -183,24 +143,18 @@ package's patch management tools directly. If the RSB does not support the
specific patch manage tool please contact the mailing list to see if support
can be added.
Patches for packages developed by the RTEMS project can be placed in the RTEMS
Tools Git repository. The ``tools`` directory in the repository has various
places a patch can live. The tree is broken down in RTEMS releases and then
tools within that release. If the package is not specific to any release the
patch can be added closer to the top under the package's name. Patches to fix
specific tool related issues for a specific architecture should be grouped
under the specific architecture and only applied when building that
architecture avoiding a patch breaking an uneffected architecture.
Referenced patches should be placed in a location that is easy to access and
download with a stable URL. We recommend attaching a patch to an RTEMS ticket
in it's bug reporting system or posting to a mailing list with online archives.
Patches in the RTEMS Tools repository need to be submitted to the upstream
project. It should not be a clearing house for patches that will not be
accepted upstream.
RTEMS's former practice of placing patches in the RTEMS Tools Git repository
has been stopped.
Patches are added to a component's name and in the ``%prep:`` section the
patches can be set up, meaning they are applied to source. The patches
are applied in the order they are added. If there is a dependency make
sure you order the patches correctly when you add them. You can add any
number of patches and the RSB will handle them efficently.
patches can be set up, meaning they are applied to source. The patches are
applied in the order they are added. If there is a dependency make sure you
order the patches correctly when you add them. You can add any number of
patches and the RSB will handle them efficently.
Patches can have options. These are added before the patch URL. If no options
are provided the patch's setup default options are used.
@ -226,15 +180,15 @@ 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 sha512 <1> gdb-sim-lm32uart.diff <2> 77d07087 ... e7db17fb <3>
.. topic:: Items:
1. The type of checksum, in the case an MD5 hash.
1. The type of checksum, in the case an SHA512 hash.
2. The patch file the checksum is for.
3. The MD5 hash.
3. The SHA512 hash.
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

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

@ -2,127 +2,311 @@
.. Copyright (C) 2012, 2016 Chris Johns <chrisj@rtems.org>
RTEMS Third-Party Packages
--------------------------
Third-Party Packages
--------------------
This section describes how to build and add an RTEMS third-party package to the
RSB.
A third-party package is a library or software package built to run on RTEMS,
examples are NTP, Net-Snmp, libjpeg or Python. These pieces of software can be
used to help build RTEMS applications. The package is built for a specific
BSP and so requires a working RTEMS tool chain and an installed RTEMS Board
Support Package (BSP).
examples are Curl, NTP, Net-Snmp, libjpeg and more. These pieces of software
can be used to help build RTEMS applications. The package is built for a
specific BSP and so requires a working RTEMS tool chain, an installed RTEMS
Board Support Package (BSP), and a network stack if the package uses
networking resources.
The RSB support for building third-party packages is based around the *pkconfig*
files (PC) installed with the BSP. The pkgconfig support in RTEMS is considered
experimental and can have some issues for some BSPs. This issue is rooted deep
in the RTEMS build system. If you have any issues with this support please ask
on the RTEMS developers mailing list.
.. sidebar:: Help
If you have any issues using, building or adding third party packages please
ask on the RTEMS users mailing list.
The RSB support for building third-party packages is based around the
*pkconfig* files (PC) installed with the BSP. The pkgconfig support in RTEMS is
considered experimental and can have some issues for some BSPs. This issue is
rooted deep in the RTEMS build system.
Vertical Integration
^^^^^^^^^^^^^^^^^^^^
The RSB supports horizontal integration with support for multiple
architectures. Adding packages to the RSB as libraries is vertical
integration. Building the GCC tool chain requires you build an assembler before
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*.
integration. Building the GCC tool chain requires you build an assembler
before you build a compiler. The same can be done for third-party libraries,
you can create build sets that stack library dependences vertically to create
a *stack*.
Building
^^^^^^^^
To build a package you need to have a suitable RTEMS tool chain and RTEMS BSP
installed. The set builder command line requires you provide the tools path,
the RTEMS host, and the prefix path to the installed RTEMS BSP. The prefix
needs to be the same as the prefix used to build RTEMS.
the RTEMS architecture (host), the BSP, and the prefix path used to the
install RTEMS BSP.
To build Net-SNMP the command is:
The RSB prefix option (``--prefix``) provided when building a package is the
path to:
#. The tools, RTEMS kernel and any dependent libraries such as LibBSD. The
package will be installed into the prefix path. This build configuration can
be used to make a complete set of development tools and libraries for a
project or product under a single path.
#. The RTEMS kernel and any dependent libraries such as LibBSD. The tools path
needs to be in the environment path (not recommended) or provided to the set
builder command by the ``--with-tools`` option. The package will be
installed into the prefix path. This build configuration can be used when
you have a set of tools used with a number of RTEMS BSPs. The tools can be
shared between the different BSPs.
#. The path the package is installed into. The tools path needs to be in the
environment path (not recommended) or provided to the set builder command
using the ``--with-tools`` option. The path to the RTEMS kernel and any
dependent libraries such as LibBSD needs to be supplied to the set builder
command using the ``--with-rtems`` option. This build configuration can be
used when you have a set of libraries you are testing with a changing RTEMS
kernel. Becareful using this configuration as changes in RTEMS interfaces
may require rebuilding these packages.
The set builder command option ``--host`` is used to provide the RTEMS
architecture the package is being built for. For example ``--host=arm-rtems5``
is used for any ARM BSP.
The set builder command option ``--with-rtems-bsp`` is the RTEMS BSP the
package is being built for. The BSP is searched for under the path provided by
the command option ``--with-rtems`` and if this option is not provided the
provided prefix is searched.
The following example builds and installs the Curl networking package for the
ARM BeagleBone Black BSP installing it into the same path the tools, RTEMS
kernel and LibBSD are installed in.
.. code-block:: none
$ cd rtems-source-builder/rtems
$ ../source-builder/sb-set-builder --log=log_sis_net_snmp \
--prefix=$HOME/development/rtems/bsps/4.11 \
--with-tools=$HOME/development/rtems/4.11 \
--host=sparc-rtems4.11 --with-rtems-bsp=erc32 4.11/net-mgmt/net-snmp
RTEMS Source Builder - Set Builder, v0.3.0
Build Set: 4.11/net-mgmt/net-snmp
config: net-mgmt/net-snmp-5.7.2.1-1.cfg
package: net-snmp-5.7.2.1-sparc-rtems4.11-1
building: net-snmp-5.7.2.1-sparc-rtems4.11-1
installing: net-snmp-5.7.2.1-sparc-rtems4.11-1 -> /Users/chris/development/rtems/bsps/4.11
cleaning: net-snmp-5.7.2.1-sparc-rtems4.11-1
Build Set: Time 0:01:10.651926
$ ../source-builder/sb-set-builder --prefix=$HOME/development/cs/rtems/5 \
--log=curl.txt --host=arm-rtems5 --with-rtems-bsp=beagleboneblack ftp/curl
RTEMS Source Builder - Set Builder, 5 (2bdae1f169e4)
Build Set: ftp/curl
config: ftp/curl-7.65.1-1.cfg
package: curl-v7.65.1-arm-rtems5-1
download: https://curl.haxx.se/download/curl-7.65.1.tar.xz -> sources/curl-7.65.1.tar.xz
downloading: sources/curl-7.65.1.tar.xz - 2.3MB of 2.3MB (100%)
building: curl-v7.65.1-arm-rtems5-1
sizes: curl-v7.65.1-arm-rtems5-1: 87.055MB (installed: 2.238MB)
cleaning: curl-v7.65.1-arm-rtems5-1
reporting: ftp/curl-7.65.1-1.cfg -> curl-v7.65.1-arm-rtems5-1.txt
reporting: ftp/curl-7.65.1-1.cfg -> curl-v7.65.1-arm-rtems5-1.xml
installing: curl-v7.65.1-arm-rtems5-1 -> /Users/chris/development/cs/rtems/5
cleaning: curl-v7.65.1-arm-rtems5-1
Build Set: Time 0:01:10.006872
Adding
^^^^^^
Adding a package requires you first build it manually by downloading the source
for the package and building it for RTEMS using the command line of a standard
shell. If the package has not been ported to RTEMS you will need to port it and
this may require you asking questions on the package's user or development
support lists as well as RTEMS's developers list. Your porting effort may end
up with a patch. RTEMS requires a patch be submitted upstream to the project's
community as well as RTEMS so it can be added to the RTEMS Tools git
repository. A patch in the RTEMS Tools git reposiitory can then be referenced
by an RSB configuration file.
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 shell. If the package has not been ported to RTEMS you will need to
port it and this may require asking questions on the package's user or
development support lists as well as RTEMS's developers list. Your porting
effort may end up with a patch. RTEMS requires a patch be submitted upstream
to the project's community as well as RTEMS. The RTEMS submission is best as a
patch attached to ticket in Trac. A patch attached to a ticket can be
referenced by an RSB configuration file and used in a build.
A package may create executables, for example NTP normally creates executables
such as ``ntdp``, ``ntpupdate``, or ``ntpdc``. These executables can be useful
when testing the package however they are of limited use by RTEMS users because
they cannot be directly linked into a user application. Users need to link to
the functions in these executables or even the executable as a function placed
in libraries. If the package does not export the code in a suitable manner
please contact the project's commuinity and see if you can work them to provide
a way for the code to be exported. This may be difficult because exporting
internal headers and functions opens the project up to API compatibility issues
they did not have before. In the simplest case attempting to get the code into
a static library with a single call entry point exported in a header would give
RTEMS user's access to the package's main functionality.
.. sidebar:: Patches in Trac
A package requires 3 files to be created:
Attaching patches for packages to Trac tickets provides an easy to reference
URL the RSB can fetch. The patch URL does not change across RTEMS versions
and it does not depend on the state or layout of a git repo.
- The first file is the RTEMS build set file and it resides in the
``rtems/config/%{rtems_version}`` path in a directory tree based on the
FreeBSD ports collection. For the NTP package and RTEMS 4.11 this is
``rtems/config/4.11/net/ntp.bset``. If you do not know the FreeBSD port path
A package may create executables, for example Curl normally creates an
executable called ``curl`` how ever it will probailty not run because the
needed RTEMS configuration is not suitable. If found the RSB automatically
adds the RTEMS library ``librtemsdefaultconfig.a`` to the ``LIBS`` variable
used to link executables. This library provides a limited configuraiton
suitable for linking an executable however it is not a set up that allows the
resulting executable to run correctly. As a result it is best not to install
these executables.
A custom RTEMS patch to an executate's source code can turn it into a function
that can be called by the RTEMS shell. Users can call the function in their
executables simulating the running of the package's command. If the package
does not export the code in a suitable manner please contact the project's
commuinity and see if you can work with them to provide a way for the code to
be exported. This may be difficult because exporting internal headers and
functions opens the project up to API compatibility issues they did not have
before. In the simplest case attempting to get the code into a static library
with a single call entry point exported in a header would give RTEMS user's
access to the package's main functionality.
A package requires at least three (3) files to be created:
Published Package Name:
The first file is the RTEMS build set file and it resides under the
``rtems/config`` path in a directory tree based on the FreeBSD ports
collection. For the Curl package and RTEMS 5 this is
``rtems/config/ftp/curl.bset``. If you do not know the FreeBSD port path
for the package you are adding please ask. The build set file references a
specific configuration file therefore linking the RTEMS version to a specific
version of the package you are adding. Updating the package to a new version
requires changing the build set to the new configuration file.
specific configuration file therefore linking the RTEMS version to a
specific version of the package you are adding. Updating the package to a
new version requires changing the build set to the new configuration file.
- The second file is an RTEMS version specific configuration file and it
includes the RSB RTEMS BSP support. These configuration files reside in the
``rtems/config`` tree again under the FreeBSD port's path name. For example
the NTP package is found in the ``net`` directory of the FreeBSD ports tree
so the NTP configuration path is ``rtems/config/net/ntp-4.2.6p5-1.cfg`` for
that specific version. The configuration file name typically provides version
specific references and the RTEMS build set file references a specific
version. This configuration file references the build configuration file held
in the common configuration file tree.
Package Version Configuration File:
The second file is an RTEMS version specific configuration file and it
includes the RSB RTEMS BSP support. These configuration files reside in
the ``rtems/config`` tree and under the FreeBSD port's path name. For
example the Curl package is found in the ``ftp`` directory of the FreeBSD
ports tree so the Curl configuration path is
``rtems/config/ftp/curl-7.65.1-1.cfg`` for that specific version. The
configuration file name typically provides version specific references and
the RTEMS build set file references a specific version. This configuration
file references the build configuration file held in the common
configuration file tree. An SHA512 hash is required to verify the source
package that is downloaded.
- The build configuration. This is a common script that builds the package. It
resides in the ``source-builder/config`` directory and typically has the
packages's name with the major version number. If the build script does not
change for each major version number a *common* base script can be created
and included by each major version configuration script. The *gcc* compiler
configuration is an example. This approach lets you branch a version if
something changes that is not backwards compatible. It is important to keep
existing versions building. The build configuration should be able to build a
package for the build host as well as RTEMS as the RSB abstracts the RTEMS
specific parts. See :ref:`Configuration` for more details.
Build Configuration File:
The build configuration. This is a common script that builds the
package. It resides in the ``source-builder/config`` directory and
typically has the packages's name with the major version number. If the
build script does not change for each major version number a *common* base
script can be created and included by each major version configuration
script. The *gcc* compiler configuration is an example. This approach lets
you branch a version if something changes that is not backwards
compatible. It is important to keep existing versions building. The build
configuration should be able to build a package for the build host as well
as RTEMS as the RSB abstracts the RTEMS specific parts. See
:ref:`Configuration` for more details.
Host and Build Flags
^^^^^^^^^^^^^^^^^^^^
A package's build is controlled by setting the compiler names and flags that
are used when building. The RSB provides a macro called
``%{host_build_flags}`` to define these flags for you. Use this macro in the
```%build`` section of your config script file to define the set up needed to
build a native package or to cross-compile to a specific host such as RTEMS
. The typical ``%build`` section is:
.. code-block:: spec
%build
build_top=$(pwd)
%{build_directory}
mkdir -p ${build_dir}
cd ${build_dir}
%{host_build_flags}
../${source_dir_curl}/configure \
--host=%{_host} \
--prefix=%{_prefix} \
--bindir=%{_bindir} \
--exec_prefix=%{_exec_prefix} \
--includedir=%{_includedir} \
--libdir=%{_libdir} \
--libexecdir=%{_libexecdir} \
--mandir=%{_mandir} \
--infodir=%{_infodir} \
--datadir=%{_datadir}
%{__make} %{?_smp_mflags} all
cd ${build_top}
The ``%{host_build_flags}`` checks if the build is native for the development
host or a cross-compile build.
For a cross-complication build the flags are:
``CC``, ``CC_FOR_HOST``:
The C compiler used to build the package. For an RTEMS build this is the
RTEMS C compiler. For example the ARM architecture and RTEMS 5 the value is
set to ``arm-rtems5-gcc``.
``CXX``, ``CXX_FOR_HOST``:
The C++ compiler used to build the package. For an RTEMS build this is the
RTEMS C++ compiler. For example the ARM architecture and RTEMS 5 the value is
set to ``arm-rtems5-g++``.
``CPPFLAGS``, ``CPPFLAGS_FOR_HOST``:
The C compiler preprocessor flags used to build the package. Set any include
paths in this variable as some configure scripts will warns you if include
paths are set in the ``CFLAGS``.
``CFLAGS``, ``CFLAGS_FOR_HOST``:
The C compiler flags used when running the C compiler. Set any include paths
in the ``CPPFLAGS`` variable as some configure scripts will warn you if
include paths in this variable.
``CXXFLAGS``, ``CXXFLAGS_FOR_HOST``:
The C++ compiler flags used when running the C++ compiler. Set any include
paths in the ``CPPFLAGS`` variable as some configure scripts will warn you if
include paths in this variable.
``LDFLAGS``, ``LDFLAGS_FOR_HOST``:
The linker flags used whne link package executables. The C or C++ compiler
is used to run the linker.
``LIBS``, ``LIBS_FOR_HOST``:
A list of libraries passed to the linker when linking an executable.
``CC_FOR_BUILD``:
The native C compiler.
``CXX_FOR_BUILD``:
The native C++ compiler.
``CPPFLAGS_FOR_BUILD``:
The C preprocessor flags used when preprocessoring a native C source file.
``CFLAGS_FOR_BUILD``:
The native C compiler flags used when running the native C compiler.
``CXXFLAGS_FOR_BUILD``:
The native C++ compiler flags used when running the native C++ compiler.
``LDFLAGS_FOR_BUILD``:
The native linker flags used when linking a native executable.
``LIBS_FOR_BUILD``:
The native libraries used to when linking a native executable.
For a native build the flags are:
``CC``, ``CC_FOR_BUILD``:
The native C compiler.
``CXX``, ``CXX_FOR_BUILD``:
The native C++ compiler.
``CPPFLAGS``, ``CPPFLAGS_FOR_BUILD``:
The C preprocessor flags used when preprocessoring a native C source file.
``CFLAGS``, ``CFLAGS_FOR_BUILD``:
The native C compiler flags used when running the native C compiler.
``CXXFLAGS``, ``CXXFLAGS_FOR_BUILD``:
The native C++ compiler flags used when running the native C++ compiler.
``LDFLAGS``, ``LDFLAGS_FOR_BUILD``:
The native linker flags used when linking a native executable.
``LIBS``, ``LIBS_FOR_BUILD``:
The native libraries used to when linking a native executable.
BSP Support
^^^^^^^^^^^
The RSB provides support to help build packages for RTEMS. RTEMS applications
can be viewed as statically linked executables operating in a single address
The RSB provides support to build packages for RTEMS. RTEMS applications can
be viewed as statically linked executables operating in a single address
space. As a result only the static libraries a package builds are required and
these libraries need to be ABI compatible with the RTEMS kernel and application
code meaning compiler ABI flags cannot be mixed when building code. The 3rd
party package need to use the same compiler flags as the BSP used to build
RTEMS.
these libraries need to be ABI compatible with the RTEMS kernel and
application code. This means the compiler ABI flags used to build all the code
in the executable must be the same. A 3rd party package must use the same
compiler flags as the BSP used to build RTEMS.
.. note::
@ -134,14 +318,15 @@ RTEMS.
The RSB provides the configuration file ``rtems/config/rtems-bsp.cfg`` to
support building third-party packages and you need to include this file in your
RTEMS version specific configuration file. For example the Net-SNMP
configuration file ``rtems/config/net-mgmt/net-snmp-5.7.2.1-1.cfg``:
RTEMS version specific configuration file. For example the Curl configuration
file ``rtems/config/curl/curl-7.65.1-1.cfg``:
.. code-block:: spec
#
# NetSNMP 5.7.2.1
# Curl 7.65.1
#
%if %{release} == %{nil}
%define release 1 <1>
%endif
@ -149,24 +334,16 @@ configuration file ``rtems/config/net-mgmt/net-snmp-5.7.2.1-1.cfg``:
%include %{_configdir}/rtems-bsp.cfg <2>
#
# NetSNMP Version
# Curl Version
#
%define net_snmp_version 5.7.2.1 <3>
%define curl_version 7.65.1 <3>
%hash sha512 curl-%{curl_version}.tar.xz aba2d979a...72b6ac55df4 <4>
#
# We need some special flags to build this version.
# Curl Build configuration
#
%define net_snmp_cflags <4> -DNETSNMP_CAN_USE_SYSCTL=1 -DARP_SCAN_FOUR_ARGUMENTS=1 -DINP_IPV6=0
#
# Patch for RTEMS support.
#
%patch add net-snmp %{rtems_git_tools}/net-snmp/rtems-net-snmp-5.7.2.1-20140623.patch <5>
#
# NetSNMP Build configuration
#
%include %{_configdir}/net-snmp-5-1.cfg <6>
%include %{_configdir}/curl-1.cfg <5>
.. topic:: Items:
@ -174,54 +351,93 @@ configuration file ``rtems/config/net-mgmt/net-snmp-5.7.2.1-1.cfg``:
2. Include the RSB RTEMS BSP support.
3. The Net-SNMP package's version.
3. The Curl package's version.
4. Add specific ``CFLAGS`` to the build process. See the
``net-snmp-5.7.2.1-1.cfg`` for details.
4. The SHA512 hash for the source file. The hash here has been shortened.
5. The RTEMS Net-SNMP patch downloaded from the RTEMS Tools git repo.
6. The Net-SNMP standard build configuration.
5. The Curl standard build configuration.
The RSB RTEMS BSP support file ``rtems/config/rtems-bsp.cfg`` checks to make
sure standard command line options are provided. These include ``--host`` and
``--with-rtems-bsp``. If the ``--with-tools`` command line option is not given
the ``${_prefix}`` is used:
sure the required RSB command line options are provided. These include
``--host`` and ``--with-rtems-bsp``. If the ``--with-tools`` command line
option is not given the ``${_prefix}`` is used as the path to the tools. If
the ``--with-rtems`` command line option is not given the ``${_prefix}`` is
used as the path to the installed RTEMS BSP.
.. note::
The RTEMS BSP and any dependent 3rd party packages must be installed to be
seen as available. A path to the location the BSP has been built will not
work.
The first check is to make sure a target is not specified. This is only used
for Canadian cross-compilication builds and currently there is no support for
RTEMS third party packages to build that way:
.. code-block:: spec
%if %{_host} == %{nil} <1>
%error No RTEMS target specified: --host=host
#
# The target is used by compilers or Cxc builds.
#
%if %{_target} != %{nil}
%error RTEMS BSP builds use --host and not --target
%endif
%ifn %{defined with_rtems_bsp} <2>
%error No RTEMS BSP specified: --with-rtems-bsp=bsp
A host is required using the ``--host`` option:
.. code-block:: spec
#
# We need a host from the user to specifiy the RTEMS architecture and major
# version.
#
%if %{_host} == %{nil} && %{rtems_bsp_error} <1>
%error No RTEMS host or BSP specified: --host=<arch>-rtems<ver>
%endif
%ifn %{defined with_tools} <3>
An RTEMS BSP is required using the ``--with-bsp`` option:
.. code-block:: spec
#
# We need a BSP from the user.
#
%ifn %{defined with_rtems_bsp}
%if %{rtems_bsp_error}
%error No RTEMS BSP specified: --rtems-bsp=arch/bsp (or --with-rtems-bsp=bsp)
%endif
%define with_rtems_bsp sparc/erc32
%endif
Check if the ``--with-tools`` or ``--with-rtems`` options have been provided
and if they are not provided use the ``--prefix`` path:
.. code-block:: spec
#
# If no tools or RTEMS provided use the prefix.
#
%ifn %{defined with_tools}
%define with_tools %{_prefix}
%endif
%ifn %{defined with_rtems}
%define with_rtems %{_prefix}
%endif
Add the tools path to the envnironment path:
.. code-block:: spec
#
# Set the path to the tools.
#
%{path prepend %{with_tools}/bin} <4>
%{path prepend %{with_tools}/bin}
.. topic:: Items:
1. Check the host has been set.
2. Check a BSP has been specified.
3. If no tools path has been provided assume they are under the
``%{_prefix}``.
4. Add the tools ``bin`` path to the system path.
RTEMS exports the build flags used in *pkgconfig* (.pc) files and the RSB can
read and manage them even when there is no pkgconfig support installed on your
build machine. Using this support we can obtain a BSP's configuration and set
some standard macros variables (``rtems/config/rtems-bsp.cfg``):
RTEMS exports the build configuration in *pkgconfig* (.pc) files. The RSB can
read these files even when there is no ``pkgconfig`` support installed on your
development machine. The *pkgconfig* support provides a BSP's configuration and
the RSB uses it to set the followng RSB macros variables:
.. code-block:: spec
@ -242,17 +458,17 @@ some standard macros variables (``rtems/config/rtems-bsp.cfg``):
1. Set the path to the BSP's pkgconfig file.
2. Let pkgconfig know this is a cross-compile build.
2. Let *pkgconfig* know this is a cross-compile build.
3. Filter flags such as warnings. Warning flags are specific to a package.
3. Filter flags such as warnings. Warning flags are specific to a package and
RTEMS exports it's warnings flags in the BSP configuration settings.
4. Ask pkgconfig for the various items we require.
4. Ask *pkgconfig* for the various settings we require.
The flags obtain by pkgconfig and given a ``rtems_bsp_`` prefix and we uses these
to set the RSB host support CFLAGS, LDFLAGS and LIBS flags. When we build a 3rd
party library your host computer is the _build_ machine and RTEMS is the _host_
machine therefore we set the ``host`` variables
(``rtems/config/rtems-bsp.cfg``):
The flags obtained by *pkgconfig* and given a ``rtems_bsp`` prefix are used to
set the RTEMS host variables ``CFLAGS``, ``LDFLAGS`` and ``LIBS``. When we
build a third party library your host computer is the **build** machine and
RTEMS is the **host** machine therefore we set the ``host`` variables:
.. code-block:: spec
@ -263,9 +479,9 @@ machine therefore we set the ``host`` variables
Finally we provide all the paths you may require when configuring a
package. Packages by default consider the ``_prefix`` the base and install
various files under this tree. The package you are building is specific to a
BSP and so needs to install into the specific BSP path under the
``_prefix``. This allows more than BSP build of this package to be install
under the same ``_prefix`` at the same time (``rtems/config/rtems-bsp.cfg``):
BSP and needs to install it's files into the RTEMS specific BSP path under the
``_prefix``. This allows more than BSP build of this package to be installed
under the same ``_prefix`` at the same time:
.. code-block:: spec
@ -291,15 +507,14 @@ under the same ``_prefix`` at the same time (``rtems/config/rtems-bsp.cfg``):
.. topic:: Items:
1. The path to the BSP.
1. The path to the installed BSP.
When you configure a package you can reference these paths and the RSB will
provide sensible default or in this case map them to the BSP
(``source-builder/config/ntp-4-1.cfg``):
provide sensible default or in this case map them to the BSP:
.. code-block:: spec
../${source_dir_ntp}/configure \ <1>
../${source_dir_curl}/configure \ <1>
--host=%{_host} \
--prefix=%{_prefix} \
--bindir=%{_bindir} \
@ -309,17 +524,93 @@ provide sensible default or in this case map them to the BSP
--libexecdir=%{_libexecdir} \
--mandir=%{_mandir} \
--infodir=%{_infodir} \
--datadir=%{_datadir} \
--disable-ipv6 \
--disable-HOPFPCI
--datadir=%{_datadir}
.. topic:: Items:
1. The configure command for NTP.
1. The configure command for Curl.
RTEMS BSP Configuration
^^^^^^^^^^^^^^^^^^^^^^^
To build a package for RTEMS you need to build it with the matching BSP
configuration. A BSP can be built with specific flags that require all code
being used needs to be built with the same flags.
BSP Configuration
^^^^^^^^^^^^^^^^^
The following RSB macros are defined when building a package for RTEMS:
.. note::
A complete list can be obtained by building with the ``--trace`` flag. The
log will contain a listing of all macros before and after the configuration
is loaded.
``%{rtems_bsp}``:
The name of the RTEMS BSP.
``%{rtems_bsp_cc}``:
The C compiler name for the RTEMS BSP.
``%{rtems_bsp_cflags}``:
The C compiler flags for the RTEMS BSP.
``%{rtems_bsp_ccflags}``:
The C++ compiler flags for the RTEMS BSP.
``%{rtems_bsp_incpath}``:
The include path to teh RTEMS BSP header files.
``%{rtems_bsp_ldflags}``:
The linker flags for the RTEMS BSP.
``%{rtems_bsp_libs}``:
The libraries used when linking an RTEMS BSP executable.
``%{rtems_bsp_prefix}``:
The prefix for the RTEMS BSP.
``%{rtems-libbsd}``:
The variable is set to ``found`` if LibBSD is available.
``%{rtems-defaultconfig}``:
The path of the RSB helper script to locate find header files or libraries.
``%{_host}``
The host triplet passed on the command line to the set builder using the
``--host`` options. This is the RTEMS architecture and version. For example
``arm-rtems5``.
``%{host_cflags}``:
The BSP ``CFLAGS`` returned by ``pkgconfig``.
``%{host_cxxflags}``:
The BSP ``CXXFLAGS`` returned by ``pkgconfig``.
``%{host_includes}``:
The BSP include paths returned by ``pkgconfig``.
``%{host_ldflags}``:
The BSP ``LDFLAGS`` returned by ``pkgconfig``.
``%{host_libs}``:
The libraries needed to be linked to create an executable. If LibBSD is
installed the library ``-lbsd`` is added. If the BSP has installed the RTEMS
default configuration library (``-lrtemsdefaultconfig``) it is added to the
list of libraries.
``%{host_build_flags}``:
This macro is defined in ``defaults.mc`` and is a series of shell commands
that set up the environment to build an RTEMS package. If the host and the
build triplets are the same it is a native build for your development host. If
the host is not the build machine it is a cross-complitation build. For either
case the following are defined.
``%{_host_os}``:
The host operating system extracted from the ``--host`` command line
option. For example the operating sstem for the host of ``arm-rtems5`` is
``rtems5``.
``%{_host_arch}``:
The host architecture extracted from the ``--host`` command line option. For
example the architecture for the host of ``arm-rtems5`` is ``arm``.
``%{_host_cpu}``:
The host cpu extracted from the ``--host`` command line option. For
example the cpu for the host of ``arm-rtems5`` is ``arm``.

23
user/start/prefixes.rst
View File

@ -20,14 +20,21 @@ under. Packages that have a prefix will place all parts under the prefix
path. Packages for your host computer typically use a default prefix of
:file:`/usr/local` on FreeBSD and Linux.
You have to select a prefix for your RTEMS tool suite installation. The RTEMS
tool suite consists of a cross tool chain (Binutils, GCC, GDB, Newlib, etc.)
for your target architecture and :ref:`other tools <HostTools>` provided by the
RTEMS Project. You build and install the tool suite with the
:ref:`RTEMS Source Builder (RSB) <RSB>`. By default, the RSB will start the
prefix path with a host operating system specific path plus :file:`rtems` plus
the RTEMS version, e.g. :file:`/opt/rtems/5` on Linux and
:file:`/usr/local/rtems/5` on FreeBSD and macOS.
You have to select a prefix for your installation. You will build and install
the RTEMS tool suite, an RTEMS kernel for a BSP and you may build and install
third party libraries. You can build them all as a stack with a single prefix
or you can
The RTEMS tool suite consists of a cross tool chain (Binutils, GCC, GDB,
Newlib, etc.) for your target architecture and :ref:`other tools <HostTools>`
provided by the RTEMS Project. The RTEMS
You build and install the tool suite with the :ref:`RTEMS Source Builder (RSB)
<RSB>`. By default, the RSB will start the prefix path with a host operating
system specific path plus :file:`rtems` plus the RTEMS version, e.g.
:file:`/opt/rtems/5` on Linux and :file:`/usr/local/rtems/5` on FreeBSD and
macOS.
It is strongly recommended to run the RSB as a *normal user* and not with
*root* privileges (also known as *super user* or *Administrator*). You have to