source: rtems-docs/user/start/basics.rst @ 2151927

.. comment: Copyright (c) 2016 Chris Johns <chrisj@rtems.org>
.. comment: All rights reserved.

.. _prefixs:

Prefixes
========

You will see the term **prefix** referred to though out this documentation and
in a wide number of software packages you can download from the internet. A
**prefix** is a path on your computer a software package is built and installed
under. Packages that have a **prefix** will place all parts under the *prefix
path*. On a host computer like Linux the packages you install from your
distribution typically use a platform specific standard *prefix*. For example
on Linux it is :file:`/usr` and on FreeBSD it is :file:`/usr/local`.

We recommend you **do not** use the standard *prefix* when installing RTEMS
Tools. If you are building the tools as a normal user and not as ``root`` the
RTEMS Source Builder (RSB) will fail if the *prefix* is not writable. We
recommend you leave the standand *prefix* for the packages your operating
system installs.

A further reason not use the standard *prefix* is to allow more than one
version of RTEMS to exist on your host machine at a time. The ``autoconf`` and
``automake`` tools required by RTEMS are not versioned and vary between RTEMS
versions. If you use a single *prefix* there is a chance things from different
versions may interact. This should not happen but it could.

For POSIX or Unix hosts the RTEMS Project uses :file:`/opt/rtems` as a standard
*prefix*. We view this *prefix* as a production level path and we place
development versions under a different *prefix* away from the production
versions. Under this top level *prefix* we place the various versions we need
for development, for example the version 4.11.0 the *prefix* would be
:file:`/opt/rtems/4.11.0`. If an update called 4.11.1 is released the *prefix*
would be :file:`/opt/rtems/4.11.1`. These are recommendations and the choice of
what you use is entirly yours. You may decide to have a single path for all
RTEMS 4.11 releases of :file:`/opt/rtems/4.11`.

For Windows a typical prefix is :file:`C:\\opt` and as an MSYS2 path this is
:file:`/c/opt`.

.. _project_sandboxing:

Project Sandboxing
==================

Project specific sandboxes let you have a number of projects running in
parallel with each project in its own sandbox. You simlpy have a prefix per
project and under that prefix you create a simple yet repeatable structure.

As an exapmle lets say I have a large disk mounted under :file:`/bd` for *Big
Disk*. As ``root`` create a directory called ``projects`` and give the
directory suitable permissions to be writable by you as a user.

Lets create a project sandbox for my *Box Sorter* project. First create a
project directory called :file:`/bd/projects/box-sorter`. Under this create
:file:`rtems` and under that create :file:`rtems-4.11.0`. Under this path you
can follow the :ref:`released-version` procedure to build a tool set using the
prefix of :file:`/bd/projects/box-sorter/rtems/4.11.0`. You are free to create
your project specific directories under :file:`/bd/projects/box-sorter`.

A variation of this is to have a single set of *production* tools and RTEMS
BSPs on the disk under :file:`/bd/rtems` you can share between your
projects. The top level directories would be:

:file:`/bd/rtems`
  The top path to production tools and kernels.

:file:`/bd/rtems/4.11.0`
  Production prefix for RTEMS 4.11.0 compiler, debuggers, tools and Board
  Support Packages (BSPs).

:file:`/bd/projects`
  Project specific development trees.

:file:`/bd/projects/box-sorter`
  Box Sorter project sandbox.

A further variation is to use the ``--without-rtems`` option with the RSB to
not build the BSPs when building the tools and to buld RTEMS specifically for
each project. This lets you have a production tools installed at a top level on
your disk and each project can have a specific and possibly customised version
of RTEMS. The top level directories would be:

:file:`/bd/rtems`
  The top path to production tools and kernels.

:file:`/bd/rtems/4.11.0`
  Production prefix for RTEMS 4.11.0.

:file:`/bd/rtems/4.11.0`
  Production prefix for RTEMS 4.11.0 compiler, debuggers and tools.

:file:`/bd/projects`
  Project specific development trees.

:file:`/bd/projects/box-sorter`
  Box Sorter project sandbox.

:file:`/bd/projects/box-sorter/rtems`
  Box Sorter project's custom RTEMS kernel source and installed BSP.

If there is an RTEMS kernel you to share between projects you can move this to
a top level and share. In this case you will end up with:

:file:`/bd/rtems`
  The top path to production tools and kernels.

:file:`/bd/rtems/4.11.0`
  Production prefix for RTEMS 4.11.0.

:file:`/bd/rtems/4.11.0/tools`
  Production prefix for RTEMS 4.11.0 compiler, debuggers and tools.

:file:`/bd/rtems/4.11.0/bsps`
  Production prefix for RTEMS 4.11.0 Board Support Packages (BSPs).

:file:`/bd/projects`
  Project specific development trees.

:file:`/bd/projects/box-sorter`
  Box Sorter project sandbox.

The project sandoxing approach allows you move a specific production part into
the project's sandbox to allow you to customise it. This is useful if you are
testing new relesaes. The typical dependency is the order listed above. You can
test new RTEMS kernels with production tools but new tools will require you
build the kernel with them. Release notes with each release will let know
what you need to update.

If the machine is a central project development machine simply replace
:file:`projects` with :file:`users` and give each user a personal directory.