source: rtems-docs/user/installation/prefixes-sandboxing.rst @ 86518bd

4.115
Last change on this file since 86518bd was 86518bd, checked in by Chris Johns <chrisj@…>, on 07/04/16 at 02:30:09

Reorganisse the User Manual to make it easier to navigate.

  • Property mode set to 100644
File size: 6.1 KB
Line 
1.. comment SPDX-License-Identifier: CC-BY-SA-4.0
2
3.. comment: Copyright (c) 2016 Chris Johns <chrisj@rtems.org>
4.. comment: All rights reserved.
5
6.. _prefixes:
7
8Prefixes
9--------
10
11.. index:: Prefixes
12
13You will see the term :ref:term:`prefix` referred to thoughout this
14documentation and in a wide number of software packages you can download from
15the internet. A **prefix** is the path on your computer a software package is
16built and installed under. Packages that have a **prefix** will place all parts
17under the **prefix** path. On a host computer like Linux the packages you
18install from your distribution typically use a platform specific standard
19**prefix**. For example on Linux it is :file:`/usr` and on FreeBSD it is
20:file:`/usr/local`.
21
22We recommend you *DO NOT* use the standard **prefix** when installing the RTEMS
23Tools. The standard **prefix** is the default **prefix** each package built by
24the RSB contains. If you are building the tools when logged in as a *Standard
25User* and not as the *Super User* (``root``) or *Administrator* the RTEMS
26Source Builder (RSB) *will* fail and report an error if the default **prefix**
27is not writable. We recommend you leave the standand **prefix** for the
28packages your operating system installs or software you manually install such
29as applications.
30
31A further reason not to use the standard **prefix** is to allow more than one
32version of RTEMS to exist on your host machine at a time. The ``autoconf`` and
33``automake`` tools required by RTEMS are not versioned and vary between the
34various versions of RTEMS. If you use a single **prefix** such as the standard
35**prefix** there is a chance parts from a package of different versions may
36interact. This should not happen but it can.
37
38For POSIX or Unix hosts, the RTEMS Project uses :file:`/opt/rtems` as it's
39standard **prefix**. We view this **prefix** as a production level path, and we
40prefer to place development versions under a different **prefix** away from the
41production versions. Under this top level **prefix** we place the various
42versions we need for development. For example the version 4.11.0 **prefix**
43would be :file:`/opt/rtems/4.11.0`. If an update called 4.11.1 is released the
44**prefix** would be :file:`/opt/rtems/4.11.1`. These are recommendations and
45the choice of what you use is entirely yours. You may decide to have a single
46path for all RTEMS 4.11 releases of :file:`/opt/rtems/4.11`.
47
48For Windows a typical **prefix** is :file:`C:\\opt\\rtems` and as an MSYS2 path
49this is :file:`/c/opt/rtems`.
50
51.. _project-sandboxing:
52
53Project Sandboxing
54------------------
55
56Project specific sandboxes let you have a number of projects running in
57parallel with each project in its own sandbox. You simply have a
58:ref:term:`prefix` per project and under that prefix you create a simple yet
59repeatable structure.
60
61As an example lets say I have a large disk mounted under :file:`/bd` for *Big
62Disk*. As ``root`` create a directory called ``projects`` and give the
63directory suitable permissions to be writable by you as a user.
64
65Lets create a project sandbox for my *Box Sorter* project. First create a
66project directory called :file:`/bd/projects/box-sorter`. Under this create
67:file:`rtems` and under that create :file:`rtems-4.11.0`. Under this path you
68can follow the :ref:`released-version` procedure to build a tool set using the
69prefix of :file:`/bd/projects/box-sorter/rtems/4.11.0`. You are free to create
70your project specific directories under :file:`/bd/projects/box-sorter`. The
71top level directories would be:
72
73:file:`/bd/projects`
74  Project specific development trees.
75
76:file:`/bd/projects/box-sorter`
77  Box Sorter project sandbox.
78
79:file:`/bd/projects/box-sorter/rtems/4.11.0`
80  Project prefix for RTEMS 4.11.0 compiler, debuggers, tools and installed
81  Board Support Package (BSP).
82
83A variation is to use the ``--without-rtems`` option with the RSB to not build
84the BSPs when building the tools and to build RTEMS specifically for each
85project. This lets you have a production tools installed at a top level on your
86disk and each project can have a specific and possibly customised version of
87RTEMS. The top level directories would be:
88
89:file:`/bd/rtems`
90  The top path to production tools.
91
92:file:`/bd/rtems/4.11.0`
93  Production prefix for RTEMS 4.11.0 compiler, debuggers and tools.
94
95:file:`/bd/projects`
96  Project specific development trees.
97
98:file:`/bd/projects/box-sorter`
99  Box Sorter project sandbox.
100
101:file:`/bd/projects/box-sorter/rtems`
102  Box Sorter project's custom RTEMS kernel source and installed BSP.
103
104A further varation if there is an RTEMS kernel you want to share between
105projects is it to move this to a top level and share. In this case you will end
106up with:
107
108:file:`/bd/rtems`
109  The top path to production tools and kernels.
110
111:file:`/bd/rtems/4.11.0`
112  Production prefix for RTEMS 4.11.0.
113
114:file:`/bd/rtems/4.11.0/tools`
115  Production prefix for RTEMS 4.11.0 compiler, debuggers and tools.
116
117:file:`/bd/rtems/4.11.0/bsps`
118  Production prefix for RTEMS 4.11.0 Board Support Packages (BSPs).
119
120:file:`/bd/projects`
121  Project specific development trees.
122
123:file:`/bd/projects/box-sorter`
124  Box Sorter project sandbox.
125
126Finally you can have a single set of *production* tools and RTEMS BSPs on the
127disk under :file:`/bd/rtems` you can share between your projects. The top level
128directories would be:
129
130:file:`/bd/rtems`
131  The top path to production tools and kernels.
132
133:file:`/bd/rtems/4.11.0`
134  Production prefix for RTEMS 4.11.0 compiler, debuggers, tools and Board
135  Support Packages (BSPs).
136
137:file:`/bd/projects`
138  Project specific development trees.
139
140:file:`/bd/projects/box-sorter`
141  Box Sorter project sandbox.
142
143The project sandoxing approach allows you move a specific production part into
144the project's sandbox to allow you to customise it. This is useful if you are
145testing new releases. The typical dependency is the order listed above. You can
146test new RTEMS kernels with production tools but new tools will require you
147build the kernel with them. Release notes with each release will let know
148what you need to update.
149
150If the machine is a central project development machine simply replace
151:file:`projects` with :file:`users` and give each user a personal directory.
Note: See TracBrowser for help on using the repository browser.