summaryrefslogtreecommitdiffstats
path: root/user
diff options
context:
space:
mode:
authorChris Johns <chrisj@rtems.org>2016-03-23 13:57:56 +1100
committerAmar Takhar <verm@darkbeer.org>2016-05-02 20:51:27 -0400
commitdc234b58f42fda847cbeac5bb59a93a152234de9 (patch)
tree4761101e46d4aed06fcff0066bdddf35d13f67a9 /user
parentc075916ddc1ea463e0fad2c0264cc49073b7b984 (diff)
downloadrtems-docs-dc234b58f42fda847cbeac5bb59a93a152234de9.tar.bz2
Corrections from a review.
Diffstat (limited to 'user')
-rw-r--r--user/start/basics.rst63
-rw-r--r--user/start/depend.rst102
-rw-r--r--user/start/releases.rst19
3 files changed, 97 insertions, 87 deletions
diff --git a/user/start/basics.rst b/user/start/basics.rst
index 28b60c9..5a6bd4e 100644
--- a/user/start/basics.rst
+++ b/user/start/basics.rst
@@ -30,14 +30,14 @@ 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
+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 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`.
+For Windows a typical prefix is :file:`C:\\opt\\rtems` and as an MSYS2 path
+this is :file:`/c/opt/rtems`.
.. _project_sandboxing:
@@ -57,18 +57,8 @@ 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).
+your project specific directories under :file:`/bd/projects/box-sorter`. The
+top level directories would be:
:file:`/bd/projects`
Project specific development trees.
@@ -76,17 +66,18 @@ projects. The top level directories would be:
: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/projects/box-sorter/rtems/4.11.0`
+ Project prefix for RTEMS 4.11.0 compiler, debuggers, tools and installed
+ Board Support Package (BSP).
-:file:`/bd/rtems`
- The top path to production tools and kernels.
+A variation is to use the ``--without-rtems`` option with the RSB to not build
+the BSPs when building the tools and to build 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/4.11.0`
- Production prefix for RTEMS 4.11.0.
+:file:`/bd/rtems`
+ The top path to production tools.
:file:`/bd/rtems/4.11.0`
Production prefix for RTEMS 4.11.0 compiler, debuggers and tools.
@@ -100,8 +91,9 @@ of RTEMS. The top level directories would be:
: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:
+A further varation if there is an RTEMS kernel you want to share between
+projects is it to 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.
@@ -121,9 +113,26 @@ a top level and share. In this case you will end up with:
:file:`/bd/projects/box-sorter`
Box Sorter project sandbox.
+Finally you can 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.
+
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
+testing new releases. 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.
diff --git a/user/start/depend.rst b/user/start/depend.rst
index f0c373f..a8ce290 100644
--- a/user/start/depend.rst
+++ b/user/start/depend.rst
@@ -14,9 +14,9 @@ RTEMS Project does not maintain binary builds of the tools. This may appear be
the opposite to what you normally experience with host operating systems, and
it is, however this approach works well. RTEMS is not a host operating system
and it is not a distrbution. Providing binary packages for every possible host
-operating system is to big a task for the RTEMS Project and it is not a good
-use of the core developer's time. Their time is better spent making RTEMS
-better and faster.
+operating system is too big a task for the RTEMS Project and it is not a good
+use of core developer time. Their time is better spent making RTEMS better and
+faster.
Developer Computer
------------------
@@ -207,76 +207,76 @@ Python
We need Python to build the tools as the RSB is written in Python and we need
suitable Python libraries to link to GDB as RTEMS makes use of GDB's Python
-support. This place specific demands on the Python we need installed and
+support. This places specific demands on the Python we need installed and
available and MSYS2 provides suitable Python versions we can use. You need to
make sure you have the correct type and version of Python installed.
We cannot use the Python executables created by the Python project (python.org)
as they are built by Microsoft's C (MSC) compiler. Linking the MSC Python
libraries with the MinGW64 executables is not easy and MSYS provided us with a
-simple solution so we do not support this.
+| simple solution so we do not support linking MSC libraries.
-MSYS2 provides two types and versions of Python executables, MinGW and MSYS and
-Python version 2 and 3. For Windows we need the MinGW executable so we have
-suitables libraries and we have to have Python version 2 because on Windows GDB
-only builds with Python2.
+| MSYS2 provides two types and versions of Python executables, MinGW and MSYS and
+| Python version 2 and 3. For Windows we need the MinGW executable so we have
+| suitables libraries and we have to have Python version 2 because on Windows GDB
+| only builds with Python2.
-You also need to install the MSYS version of Python along with the MinGW64
-Python2 package. The MSYS Python is version 3 and the RSB can support version 2
-and 3 of Python and it helps handle some of the long paths building GCC can
-generate.
+| You also need to install the MSYS version of Python along with the MinGW64
+| Python2 package. The MSYS Python is version 3 and the RSB can support version 2
+| and 3 of Python and it helps handle some of the long paths building GCC can
+| generate.
-Installing MSYS2
-~~~~~~~~~~~~~~~~
+| Installing MSYS2
+| ~~~~~~~~~~~~~~~~
-MSYS2 is installed on a new machine using the MSYS2 installer found on
-https://msys2.github.io/. Please select the ``x86_64`` variant for 64bit
-support. Run the installer followin the 7 steps listed on the page.
+| MSYS2 is installed on a new machine using the MSYS2 installer found on
+| https://msys2.github.io/. Please select the ``x86_64`` variant for 64bit
+| support. Run the installer following the 7 steps listed on the page.
-MSYS2 uses the ``pacman`` package manager. The Arch Linux project has detailed
-documentation on how to use ``pacman``. What is shown here is a just few
-examples of what you can do.
+| MSYS2 uses the ``pacman`` package manager. The Arch Linux project has detailed
+| documentation on how to use ``pacman``. What is shown here is a just few
+| examples of what you can do.
-.. sidebar:: **Pin MSYS2 Shell to Taskbar**
+| .. sidebar:: **Pin MSYS2 Shell to Taskbar**
- Pin the MSYS2 64bit Shell to the Taskbar so you always use it rather than
- the 32bit Shell.
+| Pin the MSYS2 64bit Shell to the Taskbar so you always use it rather than
+| the 32bit Shell.
-Open a 64bit MSYS shell from the Start Menu:
+| Open a 64bit MSYS shell from the Start Menu:
-.. figure:: msys2-minw64-start-menu.png
- :width: 50%
- :align: center
- :alt: MSYS2 64bit Shell Start Menu
+| .. figure:: msys2-minw64-start-menu.png
+| :width: 50%
+| :align: center
+| :alt: MSYS2 64bit Shell Start Menu
-The packages we require are:
+| The packages we require are:
- * python
- * mingw-w64-x86_64-python2
- * mingw-w64-x86_64-gcc
- * git
- * bison
- * cvs
- * diffutils
- * make
- * patch
- * tar
- * texinfo
- * unzip
+| * python
+| * mingw-w64-x86_64-python2
+| * mingw-w64-x86_64-gcc
+| * git
+| * bison
+| * cvs
+| * diffutils
+| * make
+| * patch
+| * tar
+| * texinfo
+| * unzip
-.. note::
+| .. note::
- The actual output provided may vary due to changes in the dependent packages
- or newer package versions.
+| The actual output provided may vary due to changes in the dependent packages
+| or newer package versions.
-Install the packages using ``pacman``:
+| Install the packages using ``pacman``:
-.. code-block:: shell
+| .. code-block:: shell
- ~
- $ pacman -S python mingw-w64-x86_64-python2 mingw-w64-x86_64-gcc \
- > bison cvs diffutils git make patch tar texinfo unzip
- resolving dependencies...
+| ~
+| $ pacman -S python mingw-w64-x86_64-python2 mingw-w64-x86_64-gcc \
+| bison cvs diffutils git make patch tar texinfo unzip
+| resolving dependencies...
looking for conflicting packages...
Packages (74) db-5.3.28-2 expat-2.1.0-2 gdbm-1.11-3 heimdal-1.5.3-8
diff --git a/user/start/releases.rst b/user/start/releases.rst
index 389b758..1ae0cfc 100644
--- a/user/start/releases.rst
+++ b/user/start/releases.rst
@@ -25,14 +25,14 @@ home directory called :file:`/opt/rtems`. This path will require root
access. If you are working on a machine you do not have root access to you can
use a home directory, :ref:`development-version` has more details about
this. If building on Windows use :file:`/c/opt/rtems` to keep the top level
-paths as sohrt as possible. :ref:`microsoft-windows-installation` provides more
+paths as short as possible. :ref:`microsoft-windows-installation` provides more
detail about path lengths on Windows.
-The location used to install the tools and kernel is called the `prefix`. It is
-best to have a `prefix` for each different version of RTEMS you are using. If
-you are using RTEMS 4.11 in production it is not a good to install a
-development version of 4.12 over the top. A separate `prefix` for each version
-avoids this.
+The location used to install the tools and kernel is called the
+`prefix`. :ref:`prefixes` explains prefixes and how to use them. It is best to
+have a `prefix` for each different version of RTEMS you are using. If you are
+using RTEMS 4.11 in production it is not a good to install a development
+version of 4.12 over the top. A separate `prefix` for each version avoids this.
Releases download all source packages from the RTEMS FTP server. Hosting all
the source on the RTEMS FTP server ensures the source is present for the like
@@ -41,13 +41,14 @@ RTEMS FTP the RSB will fall back to the packages home site.
.. note:: **Controlling the RTEMS Kernel Build**
- The RTEMS kernel is built by default for releases. To not build the RTEMS
+ Building releases by default builds the RTEMS kernel. To not build the RTEMS
kernel add the ``--without-rtems`` option to the RSB command line.
By default all the BSPs for an architecture are built. If you only wish to
- have a specific BSP build you can specify the BSP list by providing to the
+ have a specific BSP built you can specify the BSP list by providing to the
RSB the option ``--with-rtemsbsp``. For example to build two BSPs for the
- SPARC architecture you can supply ``--with-rtemsbsp="erc32 sis"``.
+ SPARC architecture you can supply ``--with-rtemsbsp="erc32 sis"``. This can
+ speed the build time up for some architectures that have a lot of BSPs.
This procedure will build a SPARC tool chain.