[PATCH 03/10] user: Rework Prefixes section

Thu Jan 24 11:02:58 UTC 2019

On 24/1/19 7:55 pm, Sebastian Huber wrote:
> 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

 ... host computer typically use a default ...

> +: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.

 Specific part or path?

Chris

> +: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
>  **********
>  
> 