[PATCH 03/10] user: Rework Prefixes section

Thu Jan 24 08:55:12 UTC 2019

Rename it to "Choose an Installation Prefix".

Update #3675.
---
 user/hosts/posix.rst                     |  2 +-
 user/installation/project-sandboxing.rst |  2 +-
 user/start/index.rst                     |  2 +-
 user/start/prefixes.rst                  | 74 ++++++++++++++++----------------
 user/tools/index.rst                     |  2 +
 5 files changed, 41 insertions(+), 41 deletions(-)

diff --git a/user/hosts/posix.rst b/user/hosts/posix.rst
index 365194e..063ebe2 100644
--- a/user/hosts/posix.rst
+++ b/user/hosts/posix.rst
@@ -35,7 +35,7 @@ machine. If the machine is a centralised build server the prefix may be used to
 separate production versions from the test versions and the prefix paths may
 have restricted access rights to only those who manage and have configuration
 control of the machine. We call this project sandboxing and
-:ref:`project-sandboxing` explains this in more detail.
+:ref:`ProjectSandboxing` explains this in more detail.
 
 Linux
 -----
diff --git a/user/installation/project-sandboxing.rst b/user/installation/project-sandboxing.rst
index 6c90926..248a136 100644
--- a/user/installation/project-sandboxing.rst
+++ b/user/installation/project-sandboxing.rst
@@ -2,7 +2,7 @@
 
 .. Copyright (C) 2016 Chris Johns <chrisj at rtems.org>
 
-.. _project-sandboxing:
+.. _ProjectSandboxing:
 
 Project Sandboxing
 ------------------
diff --git a/user/start/index.rst b/user/start/index.rst
index d4b6cf2..96388f2 100644
--- a/user/start/index.rst
+++ b/user/start/index.rst
@@ -57,7 +57,7 @@ place you have suitable storage. Another is permissions.  There is no
 need to become root or the administrator and we recommend you avoid
 doing this. You can build and install the tools anywhere on the host's
 file system you, as a standard user, have read and write access too.
-:ref:`Prefixes` and :ref:`project-sandboxing` provide detailed examples
+:ref:`Prefixes` and :ref:`ProjectSandboxing` provide detailed examples
 of possible locations and set ups.
 
 Simple Example
diff --git a/user/start/prefixes.rst b/user/start/prefixes.rst
index 87e76a1..e543f7d 100644
--- a/user/start/prefixes.rst
+++ b/user/start/prefixes.rst
@@ -1,48 +1,46 @@
 .. SPDX-License-Identifier: CC-BY-SA-4.0
 
+.. Copyright (C) 2019 embedded brains GmbH
+.. Copyright (C) 2019 Sebastian Huber
 .. Copyright (C) 2016 Chris Johns <chrisj at rtems.org>
 
 .. _QuickStartPrefixes:
 
-Prefixes
-========
+Choose an Installation Prefix
+=============================
 
 .. index:: prefix
 
-You will see the term :ref:term:`prefix` referred to thoughout this
+You will see the term :ref:term:`prefix` referred to throughout this
 documentation and in a wide number of software packages you can download from
-the internet. A **prefix** is the 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 the RTEMS
-Tools. The standard **prefix** is the default **prefix** each package built by
-the RSB contains. 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.
-
-A further reason not to 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 the
-various versions of RTEMS. If you use a single **prefix** such as the standard
-**prefix** there is a chance parts from a package of different versions may
-interact. This should not happen but it can.
-
-For POSIX or Unix hosts, the RTEMS Project uses :file:`/opt/rtems` as it's
-standard **prefix**. We view this **prefix** as a production level path, and we
-prefer to 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 **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 entirely 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\\rtems` and as an MSYS2 path
-this is :file:`/c/opt/rtems`.
+the internet.  It is also used in the
+`GNU Coding Standard <https://www.gnu.org/prep/standards/html_node/Directory-Variables.html>`_.
+A *prefix* is the path on your host computer a software package is installed
+under.  Packages that have a prefix will place all parts under the prefix
+path.  Packages for your host computer use typically 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 use an
+operating system specific part 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
+make sure that your normal user has sufficient privileges to create files and
+directories under the prefix.  For example, you can create a directory
+:file:`/opt/rtems` and give it to a developer group with read, write and
+execute permissions.  Alternatively, you can choose a prefix in your home
+directory, e.g. :file:`$HOME/rtems/5` or with a project-specific component
+:file:`$HOME/project-x/rtems/5`.  For more ideas, see the
+:ref:`project sandboxing <ProjectSandboxing>` section.  In this quick start
+chapter, we will choose :file:`$HOME/quick-start/rtems/5` for the RTEMS tool
+suite prefix.
+
+.. warning::
+
+    The prefix must not contain space characters.
diff --git a/user/tools/index.rst b/user/tools/index.rst
index de29ce6..98cebc4 100644
--- a/user/tools/index.rst
+++ b/user/tools/index.rst
@@ -2,6 +2,8 @@
 
 .. Copyright (C) 2017 Chris Johns <chrisj at rtems.org>
 
+.. _HostTools:
+
 Host Tools
 **********
 
-- 
2.16.4

