5.1 Prefixes

Chris Johns chrisj at rtems.org
Tue Jul 18 23:30:23 UTC 2017

On 19/07/2017 05:16, Russell Haley wrote:
> Hi,
> I'm trying to understand what I am reading so I have tried to re-write
> the sentences to my understanding.

Thank you for reporting documentation issues. Without feedback we do not know we
have issues.

Can you please create a ticket in Trac to handle the changes?

> Original:
> We recommend you DO NOT use the standard prefix when installing the
> RTEMS Tools. The standard prefix is the default prefix each package
> built by the RSB contains[1]. If you are building the tools when
> logged in as a Standard User and not as the Super User (root) or
> Administrator the RTEMS Source Builder (RSB) will fail and report an
> error if the default prefix is not writable. We recommend you leave
> the standand prefix for the packages your operating system installs or
> software you manually install such as applications.
> [1] I don't understand this line at all. Does that mean "The standard
> prefix is the default prefix as defined by each package within an
> RSB." or does it mean "All packages within an RSB build (bset) will
> install to the standard OS prefix if an alternative is not provided."
> I think the later?

A long answer, sorry, ...

The RSB has a default prefix:


It is based around the preferred FreeBSD model of placing user built packages
under '/usr/local' rather than the OS path of '/usr'. The RSB is a tool to build
packages that we use for RTEMS so we have this default prefix rather than an
RTEMS default prefix.

Internally the RSB should always provide a prefix to packages it is building.
The default prefix defined within each package in a build set can be different
and it can vary depending on the host operating systems. The RSB attempts to
make a consistent experience for users on any host so it has its own default
prefix and provides it to all packages.

The RTEMS prefix is where we install "RTEMS" and here "RTEMS" is defined as a
collection of parts. The parts are Tools, Kernel, optionally Networking, and 3rd
party libraries. These come together to create a specific set of host
executables plus target header and library files an application can use to build
an executable for a specific piece of target hardware.

A release can use the same prefix for all the RTEMS parts and they end up under
the same path so an application only needs to handle a single path to find the
tools and target header and library files. Releases can do this because all
parts are tested to work together and you do not need to vary any single part. I
recommend you install each dot point release under its own prefix. For example
'/opt/rtems/4.11.1' and '/opt/rtems/4.11.2'. This lets you build and install a
new dot point release then test while still being able to use the production
version of RTEMS your product is being released with. If you used the same
prefix you could not do this and it would be difficult to configuration control.

The 'master' branch is a little more involved and this is where 'sandboxing'
comes in. You can avoid this extra complexity and build 'master' using a single
prefix just like a release however a change in any part of RTEMS requires you
rebuild all parts. We also recommend you remove the prefix directory tree if it
exists as some files may move and that can create some unusual errors.

I will explain the more complicated 'sandboxing' to make the post complete. If
you are not concerned about this the following can be ignored. If you are
developing within RTEMS you may have a few branches being worked on and here the
ability to sandbox becomes important.

There is a layering in the parts that make up RTEMS. It is:

  bottom:  Tools (gcc, binutils, gdb)
           RTEMS Kernel
           RTEMS Networking (libbsd, optional)
           3rd Party libraries
     top:  APPLICATION

As you move from the bottom to the top of the layers the code becomes
specialised for the target hardware and then finally the application.

The 'master' branch is fluid and changes happen at all layers. A change in a
layer requires that layer and all layers above to be rebuilt. If you sandbox
each layer with a different prefix you can limit the rebuilding you need to
perform. For example you could have:

  bottom:  Tools               /opt/rtems/4.12/tools
           RTEMS Kernel        /opt/rtems/4.12/kernel
           RTEMS Networking    /opt/rtems/4.12/libbsd
           3rd Party libraries /opt/rtems/4.12/libs
     top:  APPLICATION          no prefix as it is not installed

The example here is a bit extreme as it complicates building each layer as you
move higher because you need to individually specify each prefix path, which
need to become '-I' and -L' options to the compiler and linker. If you look at
the waf options to build libbsd (based on rtems_waf.git) you can see the options
to provide the tools and kernel path.

The splitting of the parts and so the prefixes to this degree is a little
extreme and you could combine any of the layers if you are happy rebuilding all
those layers each time any of those parts change.

The defacto prefix for RTEMS has been '/opt' for a long time and I think
originated when RTEMS was only Fedora RPM based. This has evolved into
'/opt/rtems', for example '/opt/rtems/4.11'.

> Here is my rewrite:
> The RTEMS Source Builder requires the installation(?) prefix to be a
> writable path. All packages within an RSB build (bset) will install to
> the standard OS prefix if an alternative is not provided. Building to
> the standard prefix WILL fail if built as the standard user. Building
> under a privileged user will install cross compile tools into the OS
> path. We recommend you set the installation(?) prefix using either the
> --prefix command line option or .... . It is best practice to leave
> the standard OS prefix operating system use. Again, we recommend you
> DO NOT use the standard OS installation prefix when installing the
> RTEMS Tools from the Source Builder.

Lets work on this in the ticket if that is ok?


More information about the users mailing list