summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorChris Johns <chrisj@rtems.org>2016-03-22 13:42:02 +1100
committerAmar Takhar <verm@darkbeer.org>2016-05-02 20:51:27 -0400
commit21519275ccff36a51195332b23b856c7069d5aed (patch)
treea228f87f9efb6df8f50afcbfb681dec18195c987
parentAdd a basics section to Getting Started. Rearrange the content. (diff)
downloadrtems-docs-21519275ccff36a51195332b23b856c7069d5aed.tar.bz2
Corrections.
-rw-r--r--user/start/basics.rst55
-rw-r--r--user/start/depend.rst44
-rw-r--r--user/start/releases.rst5
3 files changed, 65 insertions, 39 deletions
diff --git a/user/start/basics.rst b/user/start/basics.rst
index aeba9bd..28b60c9 100644
--- a/user/start/basics.rst
+++ b/user/start/basics.rst
@@ -23,19 +23,20 @@ system installs.
A further reason not 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 RTEMS
-versions. If you use a single *prefix* then there is a chance things from
-different versions may interact. This should not happen but it could.
+versions. If you use a single *prefix* there is a chance things from different
+versions may interact. This should not happen but it could.
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, for
-example for version 4.11.0 the *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`. This choice 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 that is
+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
+: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`.
.. _project_sandboxing:
@@ -47,19 +48,20 @@ Project specific sandboxes let you have a number of projects running in
parallel with each project in its own sandbox. You simlpy have a prefix per
project and under that prefix you create a simple yet repeatable structure.
-As an exapmle lets say I have a large disk under :file:`/bd` for *Big Disk*. As
-``root`` create a directory called ``project`` and give the directory suitable
-permissions to be writable by you as a user.
+As an exapmle lets say I have a large disk mounted under :file:`/bd` for *Big
+Disk*. As ``root`` create a directory called ``projects`` and give the
+directory suitable permissions to be writable by you as a user.
-Lets create project sandbox for my *Box Sorter* project. First create a project
-directory called :file:`/bd/projects/box-sorter`. Under this create
+Lets create a project sandbox for my *Box Sorter* project. First create a
+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.
+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.
@@ -71,11 +73,14 @@ BSPs on the disk under :file:`/bd/rtems` you can share between your projects.
:file:`/bd/projects`
Project specific development trees.
-A further variation is to use the ``--without-rtems`` option with the RTEMS to
+: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.
+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`
The top path to production tools and kernels.
@@ -89,6 +94,12 @@ version of RTEMS.
:file:`/bd/projects`
Project specific development trees.
+:file:`/bd/projects/box-sorter`
+ Box Sorter project sandbox.
+
+: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:
@@ -107,9 +118,15 @@ a top level and share. In this case you will end up with:
: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
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.
+
+If the machine is a central project development machine simply replace
+:file:`projects` with :file:`users` and give each user a personal directory.
diff --git a/user/start/depend.rst b/user/start/depend.rst
index 321b984..f64e6ef 100644
--- a/user/start/depend.rst
+++ b/user/start/depend.rst
@@ -15,8 +15,8 @@ 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 developers time. Their time is better spent making RTEMS better
-and faster.
+use of the core developer's time. Their time is better spent making RTEMS
+better and faster.
Developer Computer
------------------
@@ -37,7 +37,9 @@ RTEMS makes no demands on graphics.
If you are using a VM or your host computer that is not a fast current machine
do not be concerned. The tools may take longer to build than faster hardware
however building tools is something you do once. Once the tools and RTEMS is
-built all your time can be spent writing and developing your application.
+built all your time can be spent writing and developing your application. Over
+an hour does happen and for the ARM architecture with all BSPs it can be many
+hours.
Host Software
-------------
@@ -73,10 +75,10 @@ POSIX hosts are most Unix operating systems such as Linux, FreeBSD and
NetBSD. RTEMS development works well on Unix and can scale from a single user
and a desktop machine to a team with decentralised or centralised development
infrastructure. The RTEMS project provides you with the development tools and
-aids to help you create an environment that matches the project's needs. You
-need to decide on the languages used in your project, which version control
-system, and the build system for your application. The RTEMS Project's aims to
-give complete freedom to decide what you use.
+aids to help you create an environment that matches your project's needs. The
+RTEMS Project's aims to give complete freedom to decide on the languages used
+in your project, which version control system, and the build system for your
+application.
The following are a few ways you can set up a suitable environment. You are not
limited to what is present here. A common factor that defines the final
@@ -98,18 +100,18 @@ to be built and we encourage you do not build the tools as ``root``. If you
need to control write access then it is best to manage this with groups
assigned to users.
-If you have ``root`` you can decide to install the tools under any suitable
-prefix. This may depend on the hardware in your host development machine. If
-the machine is a centralised build server the prefix may be used to separate
-production versions from the test versions and as just discussed the prefix
-paths may have restricted access to only those who manage the configuration
-control of the machine.
+If you have ``root`` access you can decide to install the tools under any
+suitable prefix. This may depend on the hardware in your host development
+machine. If the machine is a centralised build server the prefix may be used to
+separate production versions from the test versions and as just discussed the
+prefix paths may have restricted access to only those who manage and
+configuration control of the machine.
Apple OS X
----------
-Apple's OS X is fully supported. You to download and install a recent version
-of the free Apple developers application Xcode. Xocde is available in the App
+Apple's OS X is fully supported. You need to download and install a recent
+version of the Apple developer application Xcode. Xocde is available in the App
Store. Make sure you install the Command Line Tools add on available for
download within Xcode and once installed open a Terminal shell and enter the
command ``cc`` and accept the license agreement.
@@ -163,11 +165,17 @@ Windows path length is limited and can cause problems when building the
tools. The standard Windows API has a ``MAX_PATH`` length of 260
characters. This can effect some of the tools used by RTEMS. It is recommended
you keep the top level directories as short as possible when building the RTEMS
-tools and you also keep an eye on the path length when developing your
+tools and you should also keep an eye on the path length when developing your
application. The RTEMS built tools can handle much longer path lengths however
some of the GNU tools such as those in the ``binutils`` package cannot. The
-release packages of the RSB are too big to build RTEMS so you need to change
-that path to build.
+release packages of the RSB when unpacked has a top level file names that is
+too big to build RTEMS so you need to change that path to something smaller to
+build. This is indicated in :ref:`released-version`.
+
+.. _msys2_parallel_builds:
+
+Parallel Builds with Make
+~~~~~~~~~~~~~~~~~~~~~~~~~
The MSYS2 GNU ``make`` has problems when using the `jobs` option. The RSB
defaults to automatically using as many cores as the host machine has. To get a
diff --git a/user/start/releases.rst b/user/start/releases.rst
index a5bbe99..389b758 100644
--- a/user/start/releases.rst
+++ b/user/start/releases.rst
@@ -39,7 +39,7 @@ the source on the RTEMS FTP server ensures the source is present for the like
of the release on the RTEMS FTP server. If there is a problem accessing the
RTEMS FTP the RSB will fall back to the packages home site.
-.. note:: **Control the RTEMS Kernel Build**
+.. note:: **Controlling the RTEMS Kernel Build**
The RTEMS kernel is built by default for releases. To not build the RTEMS
kernel add the ``--without-rtems`` option to the RSB command line.
@@ -108,7 +108,8 @@ Build a tool chain for the SPARC architecure. We are using the SPARC
architecture in our example because GDB has a good simulator that lets us run
and test the samples RTEMS builds by default
-If building on Windows add ``--jobs=none`` to avoid GNU make issues on Windows.
+If building on Windows add ``--jobs=none`` to avoid GNU make issues on Windows
+discussed in :ref:`msys2_parallel_builds`.
.. code-block:: shell