From eae5454288e66a08e54ade1e3ad3bb74a85ccf42 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Fri, 11 Jan 2019 15:47:00 +0100 Subject: user: Rework Prefixes section Rename it to "Choose an Installation Prefix". Update #3675. --- user/start/prefixes.rst | 74 ++++++++++++++++++++++++------------------------- 1 file changed, 36 insertions(+), 38 deletions(-) (limited to 'user/start/prefixes.rst') diff --git a/user/start/prefixes.rst b/user/start/prefixes.rst index 87e76a1..2bd096f 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 .. _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 `_. +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 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 ` provided by the +RTEMS Project. You build and install the tool suite with the +:ref:`RTEMS Source Builder (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 +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 ` 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. -- cgit v1.2.3