Hello,
this is the first patch set targeting the user manual. My goal is to write an
easy to follow quick start chapter which references other chapters for the
details.
--
Sebastian Huber, embedded brains GmbH
Address : Dornierstr. 4, D-82178 Puchheim, Germany
Phone : +49 89 189 47 41-16
Fax : +49 89 189 47 41-09
E-Mail : sebastian.hu...@embedded-brains.de
PGP : Public key available on request.
Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.
From 40ec2e1636c40f77d79b6cecf6d28be091110170 Mon Sep 17 00:00:00 2001
From: Sebastian Huber <sebastian.hu...@embedded-brains.de>
Date: Fri, 11 Jan 2019 12:45:30 +0100
Subject: [PATCH 1/6] user: Move "Support" to "Introduction"
New users may find it useful to get this information in the
introduction.
---
user/index.rst | 2 -
user/overview/index.rst | 130 ++++++++++++++++++++++++++++++++++++++++++++++--
user/support/index.rst | 121 --------------------------------------------
3 files changed, 125 insertions(+), 128 deletions(-)
delete mode 100644 user/support/index.rst
diff --git a/user/index.rst b/user/index.rst
index 7ec34bd..1eda925 100644
--- a/user/index.rst
+++ b/user/index.rst
@@ -42,8 +42,6 @@ RTEMS User Manual (|version|).
tools/index
rsb/index
- support/index
-
glossary/index
* :ref:`genindex`
diff --git a/user/overview/index.rst b/user/overview/index.rst
index 3a38bc5..a3718d2 100644
--- a/user/overview/index.rst
+++ b/user/overview/index.rst
@@ -1,10 +1,10 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
Introduction
-============
+************
Overview
---------
+========
You are someone looking for a real-time operating system. This document
@@ -17,7 +17,7 @@ You are someone looking for a real-time operating system. This document
- helps you to build an example application on top of RTEMS.
Features
---------
+========
The Real-Time Executive for Multiprocessor Systems (:ref:term:`RTEMS`) is a
multi-threaded, single address-space, real-time operating system with no
@@ -182,8 +182,128 @@ RTEMS provides the following basic feature set:
- Support to stay in synchronization with FreeBSD
+Support
+=======
+.. index:: Support
+
+RTEMS offers a variety of support options.
+
+This section covers all options available to both users and developers. If you
+believe this is a bug report please submit it to the bug tracker otherwise the
+developers mailing list is the default location to send the report.
+
+RTEMS Project Support
+---------------------
+.. index:: RTEMS Project Support
+
+The following support channels are provided by the RTEMS Project and provide
+direct access to the RTEMS community.
+
+Bug Tracker
+~~~~~~~~~~~
+.. index:: Bugs
+.. index:: Reporting bugs
+
+The bug tracker can be found at the :r:url:`bugs`.
+
+See the `Submission Guidelines <http://devel.rtems.org/wiki/NewTicket/>`_ for
+details on submitting a ticket.
+
+Be sure to do a cursory search for any tickets that may be relevant to your
+problem.
+
+If you are unsure about your issue status submit a ticket and we will help you
+sort it out.
+
+Documentation
+~~~~~~~~~~~~~
+
+The latest user documentation can always be found at the :r:url:`docs`.
+
+.. _support-mailing-lists:
+
+Mailing Lists
+~~~~~~~~~~~~~
+.. index:: Community
+.. index:: Mailing lists
+
+We have several mailing lists for RTEMS users and developers.
+
+ * :r:list:`announce`
+ * Announcements for major and other project-related issues.
+
+ * :r:list:`bugs`
+ * Bugs email from :r:url:`bugs`.
+
+ * :r:list:`devel`
+ * Developers list, this is for developers of RTEMS itself.
+
+
+ * :r:list:`build`
+ * Results from the testing and building of RTEMS.
+
+ * :r:list:`users`
+ * Users of RTEMS.
+
+ * :r:list:`vc`
+ * Commits to the RTEMS master repository.
+
+
+IRC
+~~~
+.. index:: Community
+.. index:: IRC
+
+RTEMS IRC is available on the Freenode network. See the `Freenode
+<http://www.freenode.net/>`_ web site for details on connecting, selecting a
+nickname, and general usage tips. If you are new to IRC it is recommended
+reading.
+
+These are the current IRC channels.
+
+ **#rtems**
+
+This is a general channel for all things RTEMS. You can just hang out with
+other RTEMS users and developers to talk about RTEMS, using RTEMS or to make
+contact with other RTEMS users.
+
+The ``#rtems`` channel is logged. You can find the logs at
+http://www.rtems.org/irclogs/. You can search the logs using Google by adding:
+
+ **site:rtems.org inurl:irclogs**
+
+to your search terms.
+
+Developers
+~~~~~~~~~~
+.. index:: Community
+.. index:: Developers
+
+Developers can find help and support on the mailing lists, see
+:ref:`support-mailing-lists`.
+
+Technical documents including design, :r:url:`gsoc`, :r:url:`socis` can be
+found on the :r:url:`devel`.
+
+Commercial Support Services
+---------------------------
+
+The wider RTEMS community has developers and organizations who can provide
+commercial support services. These services range from training, implementing
+new features in RTEMS, deployment of RTEMS< helping establish a new project
+environment for a team, to application and system design.
+
+The RTEMS Project does not endorse or promote any provider of these services
+and we recommend you use a search engine to locate a suitable provider. If you
+are unsure please contact a provider and see what is available.
+
+If you develop a new feature or you have someone do this for you we recommend
+you have the work submitted to the project and merged. Once accepted into the
+project the work will be maintained as part of the development process within
+the project and this is a benefit for.
+
Real-time Application Systems
------------------------------
+=============================
Real-time application systems are a special class of computer applications.
They have a complex set of characteristics that distinguish them from other
@@ -218,7 +338,7 @@ competing processors are introduced. The ramifications of multiple processors
complicate each and every characteristic of a real-time system.
Real-time Executive
--------------------
+===================
Fortunately, real-time operating systems, or real-time executives, serve as a
cornerstone on which to build the application system. A real-time multitasking
diff --git a/user/support/index.rst b/user/support/index.rst
deleted file mode 100644
index 3f90ee1..0000000
--- a/user/support/index.rst
+++ /dev/null
@@ -1,121 +0,0 @@
-.. SPDX-License-Identifier: CC-BY-SA-4.0
-
-Support
-*******
-.. index:: Support
-
-RTEMS offers a variety of support options.
-
-This chapter covers all options available to both users and developers. If you
-believe this is a bug report please submit it to the bug tracker otherwise the
-developers mailing list is the default location to send the report.
-
-RTEMS Project Support
-=====================
-.. index:: RTEMS Project Support
-
-The following support channels are provided by the RTEMS Project and provide
-direct access to the RTEMS community.
-
-Bug Tracker
------------
-.. index:: Bugs
-.. index:: Reporting bugs
-
-The bug tracker can be found at the :r:url:`bugs`.
-
-See the `Submission Guidelines <http://devel.rtems.org/wiki/NewTicket/>`_ for
-details on submitting a ticket.
-
-Be sure to do a cursory search for any tickets that may be relevant to your
-problem.
-
-If you are unsure about your issue status submit a ticket and we will help you
-sort it out.
-
-Documentation
--------------
-
-The latest user documentation can always be found at the :r:url:`docs`.
-
-.. _support-mailing-lists:
-
-Mailing Lists
--------------
-.. index:: Community
-.. index:: Mailing lists
-
-We have several mailing lists for RTEMS users and developers.
-
- * :r:list:`announce`
- * Announcements for major and other project-related issues.
-
- * :r:list:`bugs`
- * Bugs email from :r:url:`bugs`.
-
- * :r:list:`devel`
- * Developers list, this is for developers of RTEMS itself.
-
-
- * :r:list:`build`
- * Results from the testing and building of RTEMS.
-
- * :r:list:`users`
- * Users of RTEMS.
-
- * :r:list:`vc`
- * Commits to the RTEMS master repository.
-
-
-IRC
----
-.. index:: Community
-.. index:: IRC
-
-RTEMS IRC is available on the Freenode network. See the `Freenode
-<http://www.freenode.net/>`_ web site for details on connecting, selecting a
-nickname, and general usage tips. If you are new to IRC it is recommended
-reading.
-
-These are the current IRC channels.
-
- **#rtems**
-
-This is a general channel for all things RTEMS. You can just hang out with
-other RTEMS users and developers to talk about RTEMS, using RTEMS or to make
-contact with other RTEMS users.
-
-The ``#rtems`` channel is logged. You can find the logs at
-http://www.rtems.org/irclogs/. You can search the logs using Google by adding:
-
- **site:rtems.org inurl:irclogs**
-
-to your search terms.
-
-Developers
-----------
-.. index:: Community
-.. index:: Developers
-
-Developers can find help and support on the mailing lists, see
-:ref:`support-mailing-lists`.
-
-Technical documents including design, :r:url:`gsoc`, :r:url:`socis` can be
-found on the :r:url:`devel`.
-
-Commercial Support Services
-===========================
-
-The wider RTEMS community has developers and orgainizations who can provide
-commercial support services. These services range from training, implementing
-new features in RTEMS, deployment of RTEMS< helping establish a new project
-environment for a team, to application and system design.
-
-The RTEMS Project does not endorse or promote any provider of these services
-and we recommend you use a search engine to locate a suitable provider. If you
-are unsrue please contact a provider and see what is available.
-
-If you develop a new feature or you have someone do this for you we recommend
-you have the work submitted to the project and merged. Once accepted into the
-project the work will be maintained as part of the development process within
-the project and this is a benefit for.
--
2.13.7
From 5970f8c709c752bdce3810e4b3055d2409130ad0 Mon Sep 17 00:00:00 2001
From: Sebastian Huber <sebastian.hu...@embedded-brains.de>
Date: Fri, 11 Jan 2019 12:54:20 +0100
Subject: [PATCH 2/6] user: Move "Ecosystem" into "Introduction"
---
user/ecosys/index.rst | 240 ------------------------------------------------
user/index.rst | 2 -
user/overview/index.rst | 239 +++++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 239 insertions(+), 242 deletions(-)
delete mode 100644 user/ecosys/index.rst
diff --git a/user/ecosys/index.rst b/user/ecosys/index.rst
deleted file mode 100644
index 201cda3..0000000
--- a/user/ecosys/index.rst
+++ /dev/null
@@ -1,240 +0,0 @@
-.. SPDX-License-Identifier: CC-BY-SA-4.0
-
-.. Copyright (C) 2016 Chris Johns <chr...@rtems.org>
-
-.. _ecosystem:
-
-Ecosystem
-*********
-.. index:: Ecosystem
-
-The RTEMS Ecosystem is the collection of tools, packages, code, documentation
-and online content provided by the RTEMS Project. The ecosystem provides a way
-to develop, maintain, and use RTEMS. It's parts interact with the user, the
-host environment, and each other to make RTEMS accessible, useable and
-predicable.
-
-The ecosystem is for users, developers and maintainers and it is an ongoing
-effort that needs your help and support. The RTEMS project is always improving
-the way it delivers the kernel to you and your feedback is important so please
-join the mailing lists and contribute back comments, success stories, bugs and
-patches.
-
-What the RTEMS project describes here to develop, maintain and use RTEMS does
-not dictate what you need to use in your project. You can and should select the
-work-flow that best suites the demands of your project and what you are
-delivering.
-
-Rational
-========
-
-RTEMS is complex and the focus of the RTEMS Ecosystem is to simplify the
-complexity for users by providing a stable documented way to build, configure
-and run RTEMS. RTEMS is more than a kernel running real-time applications on
-target hardware, it is part of a project's and therefore team's workflow and
-every project and team is different.
-
-RTEMS's ecosystem does not mandate a way to work. It is a series of parts,
-components, and items that are used to create a suitable development
-environment to work with. The processes explained in this manual are the same
-things an RTEMS maintainer does to maintain the kernel or an experienced user
-does to build their production system. It is important to keep this in mind
-when working through this manual. We encourage users to explore what can be
-done and to discover ways to make it fit their needs. The ecosystem provided by
-the RTEMS Project will not install in a single click of a mouse because we want
-users to learn the parts they will come to depend on as their project's
-development matures.
-
-The RTEMS Ecosystem provides a standard interface that is the same on all
-supported host systems. Standardizing how a user interacts with RTEMS is
-important and making that experience portable is also important. As a result
-the ecosystem is documented at the command line level and we leave GUI and IDE
-integration for users and integrators.
-
-Standardizing the parts and how to use them lets users create processes and
-procedures that are stable over releases. The RTEMS Ecosystem generates data
-that can be used to audit the build process so their configuration can be
-documented.
-
-The ecosystem is based around the source code used in the various parts,
-components and items of the RTEMS development environment. A user can create
-an archive of the complete build process including all the source code for long
-term storage. This is important for projects with a long life cycle.
-
-Open Source
-===========
-
-RTEMS is an open source operating system and an open source project and this
-extends to the ecosystem. We encourage users to integrate the processes to
-build tools, the kernel and any 3rd party libraries into their project's
-configuration management processes.
-
-All the parts that make up the ecosystem are open source. The ecosystem uses a
-package's source code to create an executable on a host so when an example
-RTEMS executable is created and run for the first time the user will have built
-every tool as well as the executable from source. The RTEMS Project believes
-the freedom this gives a user is as important as the freedom of having access
-to the source code for a package.
-
-Deployment
-==========
-
-The RTEMS Project provides the ecosystem as source code that users can download
-to create personalised development environments. The RTEMS Project does not
-provide packaging and deployment for a specific host environment, target
-architecture or BSP. The RTEMS Project encourages users and organizations to
-fill this role for the community.
-
-Building and Deploying Tool Binaries
-------------------------------------
-
-If you wish to create and distribute your build or you want to archive a build
-you can create a tar file. We term this deploying a build. This is a more
-advanced method for binary packaging and installing of tools.
-
-By default the RTEMS Source Builder installs the built packages directly and
-optionally it can also create a *build set tar file* or a *package tar file*
-per package built. The normal and default behaviour is to let the RTEMS Source
-Builder install the tools. The source will be downloaded, built, installed and
-cleaned up.
-
-The tar files are created with the full build prefix present and if you follow
-the examples given in this documentation the path is absolute. This can cause
-problems if you are installing on a host you do not have super user or
-administrator rights on because the prefix path may references part you do not
-have write access too and tar will not extract the files. You can use the
-``--strip-components`` option in tar if your host tar application supports it
-to remove the parts you do not have write access too or you may need to unpack
-the tar file somewhere and copy the file tree from the level you have write
-access from. Embedding the full prefix path in the tar files lets you know what
-the prefix is and is recommended. For example if
-``/home/chris/development/rtems/4.11`` is the prefix used you cannot change
-directory to the root (``/``) and untar the file because the ``/home`` is root
-access only. To install a tar file you have downloaded into your new machine's
-``Downloads`` directory in your home directoty you would enter:
-
-.. code-block:: shell
-
- $ cd /somewhere
- $ tar --strip-components=3 -xjf \
- $HOME/Downloads/rtems-4.11-sparc-rtems4.11-1.tar.bz2
-
-A build set tar file is created by adding ``--bset-tar-file`` option to the
-``sb-set-builder`` command::
-
- $ ../source-builder/sb-set-builder --log=l-sparc.txt \
- --prefix=$HOME/development/rtems/4.11 \
- --bset-tar-file \ <1>
- 4.11/rtems-sparc
- Source Builder - Set Builder, v0.2.0
- Build Set: 4.11/rtems-sparc
- config: expat-2.1.0-1.cfg
- package: expat-2.1.0-x86_64-freebsd9.1-1
- building: expat-2.1.0-x86_64-freebsd9.1-1
- config: tools/rtems-binutils-2.22-1.cfg
- package: sparc-rtems4.11-binutils-2.22-1
- building: sparc-rtems4.11-binutils-2.22-1
- config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg
- package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
- building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
- config: tools/rtems-gdb-7.5.1-1.cfg
- package: sparc-rtems4.11-gdb-7.5.1-1
- building: sparc-rtems4.11-gdb-7.5.1-1
- installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11 <2>
- installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
- installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
- installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
- tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2 <3>
- cleaning: expat-2.1.0-x86_64-freebsd9.1-1
- cleaning: sparc-rtems4.11-binutils-2.22-1
- cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
- cleaning: sparc-rtems4.11-gdb-7.5.1-1
- Build Set: Time 0:15:25.92873
-
-.. topic:: Items
-
- 1. The option to create a build set tar file.
-
- 2. The installation still happens unless you specify ``--no-install``.
-
- 3. Creating the build set tar file.
-
-You can also suppress installing the files using the ``--no-install``
-option. This is useful if your prefix is not accessiable, for example when
-building Canadian cross compiled tool sets::
-
- $ ../source-builder/sb-set-builder --log=l-sparc.txt \
- --prefix=$HOME/development/rtems/4.11 \
- --bset-tar-file \
- --no-install \ <1>
- 4.11/rtems-sparc
- Source Builder - Set Builder, v0.2.0
- Build Set: 4.11/rtems-sparc
- config: expat-2.1.0-1.cfg
- package: expat-2.1.0-x86_64-freebsd9.1-1
- building: expat-2.1.0-x86_64-freebsd9.1-1
- config: tools/rtems-binutils-2.22-1.cfg
- package: sparc-rtems4.11-binutils-2.22-1
- building: sparc-rtems4.11-binutils-2.22-1
- config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg
- package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
- building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
- config: tools/rtems-gdb-7.5.1-1.cfg
- package: sparc-rtems4.11-gdb-7.5.1-1
- building: sparc-rtems4.11-gdb-7.5.1-1
- tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2 <2>
- cleaning: expat-2.1.0-x86_64-freebsd9.1-1
- cleaning: sparc-rtems4.11-binutils-2.22-1
- cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
- cleaning: sparc-rtems4.11-gdb-7.5.1-1
- Build Set: Time 0:14:11.721274
- $ ls tar
- rtems-4.11-sparc-rtems4.11-1.tar.bz2
-
-.. topic:: Items
-
- 1. The option to supressing installing the packages.
-
- 2. Create the build set tar.
-
-A package tar file can be created by adding the ``--pkg-tar-files`` to the
-``sb-set-builder`` command. This creates a tar file per package built in the
-build set::
-
- $ ../source-builder/sb-set-builder --log=l-sparc.txt \
- --prefix=$HOME/development/rtems/4.11 \
- --bset-tar-file \
- --pkg-tar-files \ <1>
- --no-install 4.11/rtems-sparc
- Source Builder - Set Builder, v0.2.0
- Build Set: 4.11/rtems-sparc
- config: expat-2.1.0-1.cfg
- package: expat-2.1.0-x86_64-freebsd9.1-1
- building: expat-2.1.0-x86_64-freebsd9.1-1
- config: tools/rtems-binutils-2.22-1.cfg
- package: sparc-rtems4.11-binutils-2.22-1
- building: sparc-rtems4.11-binutils-2.22-1
- config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg
- package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
- building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
- config: tools/rtems-gdb-7.5.1-1.cfg
- package: sparc-rtems4.11-gdb-7.5.1-1
- building: sparc-rtems4.11-gdb-7.5.1-1
- tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2
- cleaning: expat-2.1.0-x86_64-freebsd9.1-1
- cleaning: sparc-rtems4.11-binutils-2.22-1
- cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
- cleaning: sparc-rtems4.11-gdb-7.5.1-1
- Build Set: Time 0:14:37.658460
- $ ls tar
- expat-2.1.0-x86_64-freebsd9.1-1.tar.bz2 sparc-rtems4.11-binutils-2.22-1.tar.bz2
- sparc-rtems4.11-gdb-7.5.1-1.tar.bz2 <2> rtems-4.11-sparc-rtems4.11-1.tar.bz2 <3>
- sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1.tar.bz2
-
-.. topic:: Items
-
- 1. The option to create packages tar files.
-
- 2. The GDB package tar file.
-
- 3. The build set tar file. All the others in a single tar file.
diff --git a/user/index.rst b/user/index.rst
index 1eda925..b61942e 100644
--- a/user/index.rst
+++ b/user/index.rst
@@ -26,8 +26,6 @@ RTEMS User Manual (|version|).
:numbered:
overview/index
- ecosys/index
-
start/index
hosts/index
installation/index
diff --git a/user/overview/index.rst b/user/overview/index.rst
index a3718d2..f00ecdf 100644
--- a/user/overview/index.rst
+++ b/user/overview/index.rst
@@ -1,5 +1,7 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
+.. Copyright (C) 2016 Chris Johns <chr...@rtems.org>
+
Introduction
************
@@ -182,6 +184,243 @@ RTEMS provides the following basic feature set:
- Support to stay in synchronization with FreeBSD
+.. _ecosystem:
+
+Ecosystem
+=========
+.. index:: Ecosystem
+
+The RTEMS Ecosystem is the collection of tools, packages, code, documentation
+and online content provided by the RTEMS Project. The ecosystem provides a way
+to develop, maintain, and use RTEMS. It's parts interact with the user, the
+host environment, and each other to make RTEMS accessible, useable and
+predicable.
+
+The ecosystem is for users, developers and maintainers and it is an ongoing
+effort that needs your help and support. The RTEMS project is always improving
+the way it delivers the kernel to you and your feedback is important so please
+join the mailing lists and contribute back comments, success stories, bugs and
+patches.
+
+What the RTEMS project describes here to develop, maintain and use RTEMS does
+not dictate what you need to use in your project. You can and should select the
+work-flow that best suites the demands of your project and what you are
+delivering.
+
+Rational
+--------
+
+RTEMS is complex and the focus of the RTEMS Ecosystem is to simplify the
+complexity for users by providing a stable documented way to build, configure
+and run RTEMS. RTEMS is more than a kernel running real-time applications on
+target hardware, it is part of a project's and therefore team's workflow and
+every project and team is different.
+
+RTEMS's ecosystem does not mandate a way to work. It is a series of parts,
+components, and items that are used to create a suitable development
+environment to work with. The processes explained in this manual are the same
+things an RTEMS maintainer does to maintain the kernel or an experienced user
+does to build their production system. It is important to keep this in mind
+when working through this manual. We encourage users to explore what can be
+done and to discover ways to make it fit their needs. The ecosystem provided by
+the RTEMS Project will not install in a single click of a mouse because we want
+users to learn the parts they will come to depend on as their project's
+development matures.
+
+The RTEMS Ecosystem provides a standard interface that is the same on all
+supported host systems. Standardizing how a user interacts with RTEMS is
+important and making that experience portable is also important. As a result
+the ecosystem is documented at the command line level and we leave GUI and IDE
+integration for users and integrators.
+
+Standardizing the parts and how to use them lets users create processes and
+procedures that are stable over releases. The RTEMS Ecosystem generates data
+that can be used to audit the build process so their configuration can be
+documented.
+
+The ecosystem is based around the source code used in the various parts,
+components and items of the RTEMS development environment. A user can create
+an archive of the complete build process including all the source code for long
+term storage. This is important for projects with a long life cycle.
+
+Open Source
+-----------
+
+RTEMS is an open source operating system and an open source project and this
+extends to the ecosystem. We encourage users to integrate the processes to
+build tools, the kernel and any 3rd party libraries into their project's
+configuration management processes.
+
+All the parts that make up the ecosystem are open source. The ecosystem uses a
+package's source code to create an executable on a host so when an example
+RTEMS executable is created and run for the first time the user will have built
+every tool as well as the executable from source. The RTEMS Project believes
+the freedom this gives a user is as important as the freedom of having access
+to the source code for a package.
+
+Deployment
+----------
+
+The RTEMS Project provides the ecosystem as source code that users can download
+to create personalised development environments. The RTEMS Project does not
+provide packaging and deployment for a specific host environment, target
+architecture or BSP. The RTEMS Project encourages users and organizations to
+fill this role for the community.
+
+Building and Deploying Tool Binaries
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you wish to create and distribute your build or you want to archive a build
+you can create a tar file. We term this deploying a build. This is a more
+advanced method for binary packaging and installing of tools.
+
+By default the RTEMS Source Builder installs the built packages directly and
+optionally it can also create a *build set tar file* or a *package tar file*
+per package built. The normal and default behaviour is to let the RTEMS Source
+Builder install the tools. The source will be downloaded, built, installed and
+cleaned up.
+
+The tar files are created with the full build prefix present and if you follow
+the examples given in this documentation the path is absolute. This can cause
+problems if you are installing on a host you do not have super user or
+administrator rights on because the prefix path may references part you do not
+have write access too and tar will not extract the files. You can use the
+``--strip-components`` option in tar if your host tar application supports it
+to remove the parts you do not have write access too or you may need to unpack
+the tar file somewhere and copy the file tree from the level you have write
+access from. Embedding the full prefix path in the tar files lets you know what
+the prefix is and is recommended. For example if
+``/home/chris/development/rtems/4.11`` is the prefix used you cannot change
+directory to the root (``/``) and untar the file because the ``/home`` is root
+access only. To install a tar file you have downloaded into your new machine's
+``Downloads`` directory in your home directoty you would enter:
+
+.. code-block:: shell
+
+ $ cd /somewhere
+ $ tar --strip-components=3 -xjf \
+ $HOME/Downloads/rtems-4.11-sparc-rtems4.11-1.tar.bz2
+
+A build set tar file is created by adding ``--bset-tar-file`` option to the
+``sb-set-builder`` command::
+
+ $ ../source-builder/sb-set-builder --log=l-sparc.txt \
+ --prefix=$HOME/development/rtems/4.11 \
+ --bset-tar-file \ <1>
+ 4.11/rtems-sparc
+ Source Builder - Set Builder, v0.2.0
+ Build Set: 4.11/rtems-sparc
+ config: expat-2.1.0-1.cfg
+ package: expat-2.1.0-x86_64-freebsd9.1-1
+ building: expat-2.1.0-x86_64-freebsd9.1-1
+ config: tools/rtems-binutils-2.22-1.cfg
+ package: sparc-rtems4.11-binutils-2.22-1
+ building: sparc-rtems4.11-binutils-2.22-1
+ config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg
+ package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
+ building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
+ config: tools/rtems-gdb-7.5.1-1.cfg
+ package: sparc-rtems4.11-gdb-7.5.1-1
+ building: sparc-rtems4.11-gdb-7.5.1-1
+ installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11 <2>
+ installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
+ installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
+ installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
+ tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2 <3>
+ cleaning: expat-2.1.0-x86_64-freebsd9.1-1
+ cleaning: sparc-rtems4.11-binutils-2.22-1
+ cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
+ cleaning: sparc-rtems4.11-gdb-7.5.1-1
+ Build Set: Time 0:15:25.92873
+
+.. topic:: Items
+
+ 1. The option to create a build set tar file.
+
+ 2. The installation still happens unless you specify ``--no-install``.
+
+ 3. Creating the build set tar file.
+
+You can also suppress installing the files using the ``--no-install``
+option. This is useful if your prefix is not accessiable, for example when
+building Canadian cross compiled tool sets::
+
+ $ ../source-builder/sb-set-builder --log=l-sparc.txt \
+ --prefix=$HOME/development/rtems/4.11 \
+ --bset-tar-file \
+ --no-install \ <1>
+ 4.11/rtems-sparc
+ Source Builder - Set Builder, v0.2.0
+ Build Set: 4.11/rtems-sparc
+ config: expat-2.1.0-1.cfg
+ package: expat-2.1.0-x86_64-freebsd9.1-1
+ building: expat-2.1.0-x86_64-freebsd9.1-1
+ config: tools/rtems-binutils-2.22-1.cfg
+ package: sparc-rtems4.11-binutils-2.22-1
+ building: sparc-rtems4.11-binutils-2.22-1
+ config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg
+ package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
+ building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
+ config: tools/rtems-gdb-7.5.1-1.cfg
+ package: sparc-rtems4.11-gdb-7.5.1-1
+ building: sparc-rtems4.11-gdb-7.5.1-1
+ tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2 <2>
+ cleaning: expat-2.1.0-x86_64-freebsd9.1-1
+ cleaning: sparc-rtems4.11-binutils-2.22-1
+ cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
+ cleaning: sparc-rtems4.11-gdb-7.5.1-1
+ Build Set: Time 0:14:11.721274
+ $ ls tar
+ rtems-4.11-sparc-rtems4.11-1.tar.bz2
+
+.. topic:: Items
+
+ 1. The option to supressing installing the packages.
+
+ 2. Create the build set tar.
+
+A package tar file can be created by adding the ``--pkg-tar-files`` to the
+``sb-set-builder`` command. This creates a tar file per package built in the
+build set::
+
+ $ ../source-builder/sb-set-builder --log=l-sparc.txt \
+ --prefix=$HOME/development/rtems/4.11 \
+ --bset-tar-file \
+ --pkg-tar-files \ <1>
+ --no-install 4.11/rtems-sparc
+ Source Builder - Set Builder, v0.2.0
+ Build Set: 4.11/rtems-sparc
+ config: expat-2.1.0-1.cfg
+ package: expat-2.1.0-x86_64-freebsd9.1-1
+ building: expat-2.1.0-x86_64-freebsd9.1-1
+ config: tools/rtems-binutils-2.22-1.cfg
+ package: sparc-rtems4.11-binutils-2.22-1
+ building: sparc-rtems4.11-binutils-2.22-1
+ config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg
+ package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
+ building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
+ config: tools/rtems-gdb-7.5.1-1.cfg
+ package: sparc-rtems4.11-gdb-7.5.1-1
+ building: sparc-rtems4.11-gdb-7.5.1-1
+ tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2
+ cleaning: expat-2.1.0-x86_64-freebsd9.1-1
+ cleaning: sparc-rtems4.11-binutils-2.22-1
+ cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
+ cleaning: sparc-rtems4.11-gdb-7.5.1-1
+ Build Set: Time 0:14:37.658460
+ $ ls tar
+ expat-2.1.0-x86_64-freebsd9.1-1.tar.bz2 sparc-rtems4.11-binutils-2.22-1.tar.bz2
+ sparc-rtems4.11-gdb-7.5.1-1.tar.bz2 <2> rtems-4.11-sparc-rtems4.11-1.tar.bz2 <3>
+ sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1.tar.bz2
+
+.. topic:: Items
+
+ 1. The option to create packages tar files.
+
+ 2. The GDB package tar file.
+
+ 3. The build set tar file. All the others in a single tar file.
+
Support
=======
.. index:: Support
--
2.13.7
From d64fc18e8376a4955703fd164a3ea18bfaa4feff Mon Sep 17 00:00:00 2001
From: Sebastian Huber <sebastian.hu...@embedded-brains.de>
Date: Fri, 11 Jan 2019 13:54:10 +0100
Subject: [PATCH 3/6] user: Move deployment details to RSB chapter
---
user/overview/index.rst | 157 +----------------------------------------------
user/rsb/deployment.rst | 159 ++++++++++++++++++++++++++++++++++++++++++++++++
user/rsb/index.rst | 3 +
3 files changed, 164 insertions(+), 155 deletions(-)
create mode 100644 user/rsb/deployment.rst
diff --git a/user/overview/index.rst b/user/overview/index.rst
index f00ecdf..c3e0f71 100644
--- a/user/overview/index.rst
+++ b/user/overview/index.rst
@@ -265,161 +265,8 @@ The RTEMS Project provides the ecosystem as source code that users can download
to create personalised development environments. The RTEMS Project does not
provide packaging and deployment for a specific host environment, target
architecture or BSP. The RTEMS Project encourages users and organizations to
-fill this role for the community.
-
-Building and Deploying Tool Binaries
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you wish to create and distribute your build or you want to archive a build
-you can create a tar file. We term this deploying a build. This is a more
-advanced method for binary packaging and installing of tools.
-
-By default the RTEMS Source Builder installs the built packages directly and
-optionally it can also create a *build set tar file* or a *package tar file*
-per package built. The normal and default behaviour is to let the RTEMS Source
-Builder install the tools. The source will be downloaded, built, installed and
-cleaned up.
-
-The tar files are created with the full build prefix present and if you follow
-the examples given in this documentation the path is absolute. This can cause
-problems if you are installing on a host you do not have super user or
-administrator rights on because the prefix path may references part you do not
-have write access too and tar will not extract the files. You can use the
-``--strip-components`` option in tar if your host tar application supports it
-to remove the parts you do not have write access too or you may need to unpack
-the tar file somewhere and copy the file tree from the level you have write
-access from. Embedding the full prefix path in the tar files lets you know what
-the prefix is and is recommended. For example if
-``/home/chris/development/rtems/4.11`` is the prefix used you cannot change
-directory to the root (``/``) and untar the file because the ``/home`` is root
-access only. To install a tar file you have downloaded into your new machine's
-``Downloads`` directory in your home directoty you would enter:
-
-.. code-block:: shell
-
- $ cd /somewhere
- $ tar --strip-components=3 -xjf \
- $HOME/Downloads/rtems-4.11-sparc-rtems4.11-1.tar.bz2
-
-A build set tar file is created by adding ``--bset-tar-file`` option to the
-``sb-set-builder`` command::
-
- $ ../source-builder/sb-set-builder --log=l-sparc.txt \
- --prefix=$HOME/development/rtems/4.11 \
- --bset-tar-file \ <1>
- 4.11/rtems-sparc
- Source Builder - Set Builder, v0.2.0
- Build Set: 4.11/rtems-sparc
- config: expat-2.1.0-1.cfg
- package: expat-2.1.0-x86_64-freebsd9.1-1
- building: expat-2.1.0-x86_64-freebsd9.1-1
- config: tools/rtems-binutils-2.22-1.cfg
- package: sparc-rtems4.11-binutils-2.22-1
- building: sparc-rtems4.11-binutils-2.22-1
- config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg
- package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
- building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
- config: tools/rtems-gdb-7.5.1-1.cfg
- package: sparc-rtems4.11-gdb-7.5.1-1
- building: sparc-rtems4.11-gdb-7.5.1-1
- installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11 <2>
- installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
- installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
- installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
- tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2 <3>
- cleaning: expat-2.1.0-x86_64-freebsd9.1-1
- cleaning: sparc-rtems4.11-binutils-2.22-1
- cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
- cleaning: sparc-rtems4.11-gdb-7.5.1-1
- Build Set: Time 0:15:25.92873
-
-.. topic:: Items
-
- 1. The option to create a build set tar file.
-
- 2. The installation still happens unless you specify ``--no-install``.
-
- 3. Creating the build set tar file.
-
-You can also suppress installing the files using the ``--no-install``
-option. This is useful if your prefix is not accessiable, for example when
-building Canadian cross compiled tool sets::
-
- $ ../source-builder/sb-set-builder --log=l-sparc.txt \
- --prefix=$HOME/development/rtems/4.11 \
- --bset-tar-file \
- --no-install \ <1>
- 4.11/rtems-sparc
- Source Builder - Set Builder, v0.2.0
- Build Set: 4.11/rtems-sparc
- config: expat-2.1.0-1.cfg
- package: expat-2.1.0-x86_64-freebsd9.1-1
- building: expat-2.1.0-x86_64-freebsd9.1-1
- config: tools/rtems-binutils-2.22-1.cfg
- package: sparc-rtems4.11-binutils-2.22-1
- building: sparc-rtems4.11-binutils-2.22-1
- config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg
- package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
- building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
- config: tools/rtems-gdb-7.5.1-1.cfg
- package: sparc-rtems4.11-gdb-7.5.1-1
- building: sparc-rtems4.11-gdb-7.5.1-1
- tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2 <2>
- cleaning: expat-2.1.0-x86_64-freebsd9.1-1
- cleaning: sparc-rtems4.11-binutils-2.22-1
- cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
- cleaning: sparc-rtems4.11-gdb-7.5.1-1
- Build Set: Time 0:14:11.721274
- $ ls tar
- rtems-4.11-sparc-rtems4.11-1.tar.bz2
-
-.. topic:: Items
-
- 1. The option to supressing installing the packages.
-
- 2. Create the build set tar.
-
-A package tar file can be created by adding the ``--pkg-tar-files`` to the
-``sb-set-builder`` command. This creates a tar file per package built in the
-build set::
-
- $ ../source-builder/sb-set-builder --log=l-sparc.txt \
- --prefix=$HOME/development/rtems/4.11 \
- --bset-tar-file \
- --pkg-tar-files \ <1>
- --no-install 4.11/rtems-sparc
- Source Builder - Set Builder, v0.2.0
- Build Set: 4.11/rtems-sparc
- config: expat-2.1.0-1.cfg
- package: expat-2.1.0-x86_64-freebsd9.1-1
- building: expat-2.1.0-x86_64-freebsd9.1-1
- config: tools/rtems-binutils-2.22-1.cfg
- package: sparc-rtems4.11-binutils-2.22-1
- building: sparc-rtems4.11-binutils-2.22-1
- config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg
- package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
- building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
- config: tools/rtems-gdb-7.5.1-1.cfg
- package: sparc-rtems4.11-gdb-7.5.1-1
- building: sparc-rtems4.11-gdb-7.5.1-1
- tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2
- cleaning: expat-2.1.0-x86_64-freebsd9.1-1
- cleaning: sparc-rtems4.11-binutils-2.22-1
- cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
- cleaning: sparc-rtems4.11-gdb-7.5.1-1
- Build Set: Time 0:14:37.658460
- $ ls tar
- expat-2.1.0-x86_64-freebsd9.1-1.tar.bz2 sparc-rtems4.11-binutils-2.22-1.tar.bz2
- sparc-rtems4.11-gdb-7.5.1-1.tar.bz2 <2> rtems-4.11-sparc-rtems4.11-1.tar.bz2 <3>
- sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1.tar.bz2
-
-.. topic:: Items
-
- 1. The option to create packages tar files.
-
- 2. The GDB package tar file.
-
- 3. The build set tar file. All the others in a single tar file.
+fill this role for the community. The :ref:`RTEMS Source Builder <RSB>`
+provides some aid to :ref:`build and deploy tool binaries <RSBDeployment>`.
Support
=======
diff --git a/user/rsb/deployment.rst b/user/rsb/deployment.rst
new file mode 100644
index 0000000..3bb9e0a
--- /dev/null
+++ b/user/rsb/deployment.rst
@@ -0,0 +1,159 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2016 Chris Johns <chr...@rtems.org>
+
+.. _RSBDeployment:
+
+Building and Deploying Tool Binaries
+====================================
+
+If you wish to create and distribute your build or you want to archive a build
+you can create a tar file. We term this deploying a build. This is a more
+advanced method for binary packaging and installing of tools.
+
+By default the RTEMS Source Builder installs the built packages directly and
+optionally it can also create a *build set tar file* or a *package tar file*
+per package built. The normal and default behaviour is to let the RTEMS Source
+Builder install the tools. The source will be downloaded, built, installed and
+cleaned up.
+
+The tar files are created with the full build prefix present and if you follow
+the examples given in this documentation the path is absolute. This can cause
+problems if you are installing on a host you do not have super user or
+administrator rights on because the prefix path may references part you do not
+have write access too and tar will not extract the files. You can use the
+``--strip-components`` option in tar if your host tar application supports it
+to remove the parts you do not have write access too or you may need to unpack
+the tar file somewhere and copy the file tree from the level you have write
+access from. Embedding the full prefix path in the tar files lets you know what
+the prefix is and is recommended. For example if
+``/home/chris/development/rtems/4.11`` is the prefix used you cannot change
+directory to the root (``/``) and untar the file because the ``/home`` is root
+access only. To install a tar file you have downloaded into your new machine's
+``Downloads`` directory in your home directoty you would enter:
+
+.. code-block:: shell
+
+ $ cd /somewhere
+ $ tar --strip-components=3 -xjf \
+ $HOME/Downloads/rtems-4.11-sparc-rtems4.11-1.tar.bz2
+
+A build set tar file is created by adding ``--bset-tar-file`` option to the
+``sb-set-builder`` command::
+
+ $ ../source-builder/sb-set-builder --log=l-sparc.txt \
+ --prefix=$HOME/development/rtems/4.11 \
+ --bset-tar-file \ <1>
+ 4.11/rtems-sparc
+ Source Builder - Set Builder, v0.2.0
+ Build Set: 4.11/rtems-sparc
+ config: expat-2.1.0-1.cfg
+ package: expat-2.1.0-x86_64-freebsd9.1-1
+ building: expat-2.1.0-x86_64-freebsd9.1-1
+ config: tools/rtems-binutils-2.22-1.cfg
+ package: sparc-rtems4.11-binutils-2.22-1
+ building: sparc-rtems4.11-binutils-2.22-1
+ config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg
+ package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
+ building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
+ config: tools/rtems-gdb-7.5.1-1.cfg
+ package: sparc-rtems4.11-gdb-7.5.1-1
+ building: sparc-rtems4.11-gdb-7.5.1-1
+ installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11 <2>
+ installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
+ installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
+ installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
+ tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2 <3>
+ cleaning: expat-2.1.0-x86_64-freebsd9.1-1
+ cleaning: sparc-rtems4.11-binutils-2.22-1
+ cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
+ cleaning: sparc-rtems4.11-gdb-7.5.1-1
+ Build Set: Time 0:15:25.92873
+
+.. topic:: Items
+
+ 1. The option to create a build set tar file.
+
+ 2. The installation still happens unless you specify ``--no-install``.
+
+ 3. Creating the build set tar file.
+
+You can also suppress installing the files using the ``--no-install``
+option. This is useful if your prefix is not accessiable, for example when
+building Canadian cross compiled tool sets::
+
+ $ ../source-builder/sb-set-builder --log=l-sparc.txt \
+ --prefix=$HOME/development/rtems/4.11 \
+ --bset-tar-file \
+ --no-install \ <1>
+ 4.11/rtems-sparc
+ Source Builder - Set Builder, v0.2.0
+ Build Set: 4.11/rtems-sparc
+ config: expat-2.1.0-1.cfg
+ package: expat-2.1.0-x86_64-freebsd9.1-1
+ building: expat-2.1.0-x86_64-freebsd9.1-1
+ config: tools/rtems-binutils-2.22-1.cfg
+ package: sparc-rtems4.11-binutils-2.22-1
+ building: sparc-rtems4.11-binutils-2.22-1
+ config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg
+ package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
+ building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
+ config: tools/rtems-gdb-7.5.1-1.cfg
+ package: sparc-rtems4.11-gdb-7.5.1-1
+ building: sparc-rtems4.11-gdb-7.5.1-1
+ tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2 <2>
+ cleaning: expat-2.1.0-x86_64-freebsd9.1-1
+ cleaning: sparc-rtems4.11-binutils-2.22-1
+ cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
+ cleaning: sparc-rtems4.11-gdb-7.5.1-1
+ Build Set: Time 0:14:11.721274
+ $ ls tar
+ rtems-4.11-sparc-rtems4.11-1.tar.bz2
+
+.. topic:: Items
+
+ 1. The option to supressing installing the packages.
+
+ 2. Create the build set tar.
+
+A package tar file can be created by adding the ``--pkg-tar-files`` to the
+``sb-set-builder`` command. This creates a tar file per package built in the
+build set::
+
+ $ ../source-builder/sb-set-builder --log=l-sparc.txt \
+ --prefix=$HOME/development/rtems/4.11 \
+ --bset-tar-file \
+ --pkg-tar-files \ <1>
+ --no-install 4.11/rtems-sparc
+ Source Builder - Set Builder, v0.2.0
+ Build Set: 4.11/rtems-sparc
+ config: expat-2.1.0-1.cfg
+ package: expat-2.1.0-x86_64-freebsd9.1-1
+ building: expat-2.1.0-x86_64-freebsd9.1-1
+ config: tools/rtems-binutils-2.22-1.cfg
+ package: sparc-rtems4.11-binutils-2.22-1
+ building: sparc-rtems4.11-binutils-2.22-1
+ config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg
+ package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
+ building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
+ config: tools/rtems-gdb-7.5.1-1.cfg
+ package: sparc-rtems4.11-gdb-7.5.1-1
+ building: sparc-rtems4.11-gdb-7.5.1-1
+ tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2
+ cleaning: expat-2.1.0-x86_64-freebsd9.1-1
+ cleaning: sparc-rtems4.11-binutils-2.22-1
+ cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
+ cleaning: sparc-rtems4.11-gdb-7.5.1-1
+ Build Set: Time 0:14:37.658460
+ $ ls tar
+ expat-2.1.0-x86_64-freebsd9.1-1.tar.bz2 sparc-rtems4.11-binutils-2.22-1.tar.bz2
+ sparc-rtems4.11-gdb-7.5.1-1.tar.bz2 <2> rtems-4.11-sparc-rtems4.11-1.tar.bz2 <3>
+ sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1.tar.bz2
+
+.. topic:: Items
+
+ 1. The option to create packages tar files.
+
+ 2. The GDB package tar file.
+
+ 3. The build set tar file. All the others in a single tar file.
diff --git a/user/rsb/index.rst b/user/rsb/index.rst
index 62a3ccf..1f64b51 100644
--- a/user/rsb/index.rst
+++ b/user/rsb/index.rst
@@ -4,6 +4,8 @@
.. highlight:: shell
+.. _RSB:
+
RTEMS Source Builder
====================
@@ -89,5 +91,6 @@ configuration can read the remaining sections.
third-party-packages
configuration
commands
+ deployment
bug-reporting
history
--
2.13.7
From f594591d1e05b06976b04669cec2749085ab3bf5 Mon Sep 17 00:00:00 2001
From: Sebastian Huber <sebastian.hu...@embedded-brains.de>
Date: Fri, 11 Jan 2019 14:44:36 +0100
Subject: [PATCH 4/6] user: Rework "Hardware" chapter
Rename it to "Target Hardware". Remove BSPs section and reference the
BSPs chapter instead. Remove explicit list of architectures and
reference the BSPs chapter instead. Fix typos. Elaborate multilib
description in the architecture section.
---
user/bsps/index.rst | 46 +++++++++--------
user/exe/index.rst | 2 +
user/glossary/index.rst | 3 ++
user/hardware/architectures.rst | 108 ++++++++++++++++++++++++++--------------
user/hardware/bsps.rst | 24 ---------
user/hardware/index.rst | 9 ++--
user/hardware/targets.rst | 28 +++++------
user/index.rst | 4 +-
8 files changed, 120 insertions(+), 104 deletions(-)
delete mode 100644 user/hardware/bsps.rst
diff --git a/user/bsps/index.rst b/user/bsps/index.rst
index e5acfd7..a8035e1 100644
--- a/user/bsps/index.rst
+++ b/user/bsps/index.rst
@@ -2,7 +2,7 @@
.. Copyright (C) 2018 embedded brains GmbH
-.. _BoardSupportPackages:
+.. _BSPs:
Board Support Packages
**********************
@@ -16,24 +16,30 @@ applications.
RTEMS contains a large number of BSPs for commonly available simulators and
target hardware.
+You can see the current BSP list in the RTEMS sources by asking RTEMS with:
+
+.. code-block:: shell
+
+ $ ./rtems-bsps
+
.. toctree::
- bsps-aarch64
- bsps-arm
- bsps-bfin
- bsps-epiphany
- bsps-i386
- bsps-lm32
- bsps-m68k
- bsps-microblaze
- bsps-mips
- bsps-moxie
- bsps-nios2
- bsps-or1k
- bsps-powerpc
- bsps-riscv
- bsps-sh
- bsps-sparc64
- bsps-sparc
- bsps-v850
- bsps-x86_64
+ bsps-aarch64
+ bsps-arm
+ bsps-bfin
+ bsps-epiphany
+ bsps-i386
+ bsps-lm32
+ bsps-m68k
+ bsps-microblaze
+ bsps-mips
+ bsps-moxie
+ bsps-nios2
+ bsps-or1k
+ bsps-powerpc
+ bsps-riscv
+ bsps-sh
+ bsps-sparc64
+ bsps-sparc
+ bsps-v850
+ bsps-x86_64
diff --git a/user/exe/index.rst b/user/exe/index.rst
index 9380a00..136a410 100644
--- a/user/exe/index.rst
+++ b/user/exe/index.rst
@@ -2,6 +2,8 @@
.. Copyright (C) 2018 Chris Johns <chr...@rtems.org>
+.. _Executables:
+
Executables
***********
.. index:: Executable
diff --git a/user/glossary/index.rst b/user/glossary/index.rst
index 2258925..5648b39 100644
--- a/user/glossary/index.rst
+++ b/user/glossary/index.rst
@@ -6,6 +6,9 @@ Glossary
.. glossary::
+ ABI
+ Application Binary Interface
+
Architecture
Family or class of processor based around a common instruction set. RTEMS
architectures follow the GCC architecture model as RTEMS needs an GCC
diff --git a/user/hardware/architectures.rst b/user/hardware/architectures.rst
index 02bcbe0..5328db8 100644
--- a/user/hardware/architectures.rst
+++ b/user/hardware/architectures.rst
@@ -1,30 +1,83 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
+.. Copyright (C) 2019 embedded brains GmbH
+.. Copyright (C) 2019 Sebastian Huber
.. Copyright (C) 2016 Chris Johns <chr...@rtems.org>
Architectures
=============
.. index:: Architectures
-An RTEMS architecture is a class or family of a processor that RTEMS
-supports. The RTEMS architecture model follows the architecture model of
+An RTEMS architecture is a class or family of a processor architecture that
+RTEMS supports. The RTEMS architecture model follows the architecture model of
GCC. An architecture in GCC results in a specific RTEMS GCC compiler. This
compiler may support a range of processors in the family that may have
-differences in instructions sets or floating point support. RTEMS configures
-GCC to create separate runtime libraries for each supported instruction set and
-floating point unit in the architecture. This is termed **multlib**. Multlibs
-are manage automatically by GCC by selecting a specific instruction set or
-specific device in a family.
-
-RTEMS executables are statically linked for a specific target therefore a
-precise and exact match can be made for the hardware that extracts the best
-possible performance. The compiler supports the variants to the instruction set
-and RTEMS extends the specialization to specific processors in an
-architecture. This specialization gives RTEMS a finer resolution of features
-and capabilites a specific device may offer allowing the kernel, drivers and
-application to make the most of those resources. The trade off is portability
-however this is not important because the executable are statically linked for
-a single target.
+differences in instructions sets, floating point support or other aspects.
+RTEMS configures GCC to create separate runtime libraries for each supported
+instruction set, floating point unit, vector unit, word size (e.g. 32-bit and
+64-bit), endianess, code model, :ref:term:`ABI`, processor errata workarounds,
+and so on in the architecture. This is termed *multilib*. Multilibs are chosen
+automatically by GCC via selecting a specific set of machine options.
+
+You can query the multilibs of a specific RTEMS GCC compiler via the
+``-print-multi-lib`` option:
+
+.. code-block:: shell
+
+ $ sparc-rtems5-gcc -print-multi-lib
+ .;
+ soft;@msoft-float
+ v8;@mcpu=v8
+ leon3;@mcpu=leon3
+ leon3v7;@mcpu=leon3v7
+ leon;@mcpu=leon
+ leon3/gr712rc;@mcpu=leon3@mfix-gr712rc
+ leon3v7/gr712rc;@mcpu=leon3v7@mfix-gr712rc
+ leon/ut699;@mcpu=leon@mfix-ut699
+ leon/at697f;@mcpu=leon@mfix-at697f
+ soft/v8;@msoft-float@mcpu=v8
+ soft/leon3;@msoft-float@mcpu=leon3
+ soft/leon3v7;@msoft-float@mcpu=leon3v7
+ soft/leon;@msoft-float@mcpu=leon
+ soft/leon3/gr712rc;@msoft-float@mcpu=leon3@mfix-gr712rc
+ soft/leon3v7/gr712rc;@msoft-float@mcpu=leon3v7@mfix-gr712rc
+ soft/leon/ut699;@msoft-float@mcpu=leon@mfix-ut699
+ soft/leon/at697f;@msoft-float@mcpu=leon@mfix-at697f
+
+Each printed line represents a multilib. The ``.`` corresponds to the default
+multilib. It is used if a set of machine options does not match to a
+specialized multilib. The string before the ``;`` describes the directory in
+the GCC installation used for the particular multilib. After the ``;`` the set
+of machine options for this multilib follows separated by ``@`` characters.
+
+You can figure out the multilib selected by GCC for a set of machine options
+with the ``-print-multi-directory`` option:
+
+.. code-block:: shell
+
+ $ sparc-rtems5-gcc -print-multi-directory -mcpu=leon3
+ leon3
+
+It is crucial that the RTEMS BSP, support libraries and the application code
+are compiled consistently with a compatible set of machine options. Otherwise,
+in the best case errors during linking will occur or you may end up silently
+with undefined behaviour which results in sporadic run-time crashes. A wrong
+set of machine options may result in a running application, however, with
+degraded performance, e.g. hardware floating point unit is not used by the
+mathematical library.
+
+For a list of architectures supported by RTEMS please have a look at the
+sections of the :ref:`Board Support Packages <BSPs>` chapter.
+
+:ref:`RTEMS executables <Executables>` are statically linked for a specific
+target therefore a precise and exact match can be made for the hardware that
+extracts the best possible performance. The compiler supports the variants to
+the instruction set and RTEMS extends the specialization to specific processors
+in an architecture. This specialization gives RTEMS a finer resolution of
+features and capabilities a specific device may offer allowing the kernel,
+drivers and application to make the most of those resources. The trade off is
+portability however this is not important because the executable are statically
+linked for a single target.
.. note::
@@ -32,24 +85,3 @@ a single target.
interface. Loading code via this interface results in an executable image
that is equivalent to statically linked executable of the same code. Dynamic
loading is a system level tool for system architects.
-
-RTEMS supports 18 architectures:
-
-- arm
-- bfin
-- epiphany
-- i386
-- lm32
-- m68k
-- mips
-- moxie
-- nios2
-- no_cpu
-- or1k
-- riscv
-- powerpc
-- sh
-- sparc
-- sparc64
-- v850
-- x86_64
diff --git a/user/hardware/bsps.rst b/user/hardware/bsps.rst
deleted file mode 100644
index c55747d..0000000
--- a/user/hardware/bsps.rst
+++ /dev/null
@@ -1,24 +0,0 @@
-.. SPDX-License-Identifier: CC-BY-SA-4.0
-
-.. Copyright (C) 2016 Chris Johns <chr...@rtems.org>
-
-.. _bsps:
-
-Board Support Packages (BSP)
-============================
-.. index:: Board Support Package
-.. index:: BSP
-
-A Board Suport Package is a historical term for a package of code, and
-supporting documentation for a target. The sparation is still important today
-for users with custom hardware.
-
-RTEMS includes 173 board support packages in it's source tree and this is a
-small number of actual targets running because it does not take into account
-the custom targets.
-
-You can see the BSP list in RTEMS by asking RTEMS with:
-
-.. code-block:: shell
-
- $ ./rtems-bsps
diff --git a/user/hardware/index.rst b/user/hardware/index.rst
index ea2c3ab..0442c4f 100644
--- a/user/hardware/index.rst
+++ b/user/hardware/index.rst
@@ -4,16 +4,13 @@
.. _Hardware:
-Hardware
-********
+Target Hardware
+***************
.. index:: Hardware
-
-This section discusses supported Hardware, Architectures, Board Support
-Packages, and running RTEMS on real hardware and simulators.
+.. index:: Target Hardware
.. toctree::
targets
architectures
- bsps
tiers
diff --git a/user/hardware/targets.rst b/user/hardware/targets.rst
index 943d77b..4d5e87f 100644
--- a/user/hardware/targets.rst
+++ b/user/hardware/targets.rst
@@ -8,19 +8,19 @@ Targets
=======
.. index:: Targets
-Hardware that can run RTEMS is often referred to as a *target* because RTEMS is
-specifically aimed at that hardware or target. An RTEMS executable is
-statically linked and executes in a single address space on the target
-hardware. A statically linked executable means the RTEMS Kernel, drivers, third
-party packages and application code is linked into a single executable image. A
-single address space means no virtual memory and no memory protected process
-address space is running within the RTEMS arena and the RTEMS Kernel, drivers
-and application have unprotected access to the whole address space and all
-hardware.
-
-Target hardware supported by RTEMS has a Board Support Package or BSP. A BSP is
-a specific instance of an RTEMS architecture that allows the creation of an
-RTEMS executable. You can view the layering as:
+*Target hardware* that can run RTEMS is often referred to simply as the
+*target* because RTEMS is specifically aimed at that target hardware. An RTEMS
+executable is statically linked and executes in a single address space on the
+target hardware. A statically linked executable means the RTEMS Kernel,
+drivers, third party packages and application code is linked into a single
+executable image. A single address space means no virtual memory and no memory
+protected process address space is running within the RTEMS arena and the RTEMS
+executive, drivers and application have unprotected access to the whole address
+space and all hardware.
+
+Target hardware supported by RTEMS has a :ref:`Board Support Package <BSPs>` or
+BSP. A BSP is a specific instance of an RTEMS architecture that allows the
+creation of an RTEMS executable. You can view the layering as:
.. comment Build image with:
.. comment aafigure hw-layers.txt --textual --type png --option
@@ -31,7 +31,7 @@ RTEMS executable. You can view the layering as:
:align: center
:alt: Software Layers on Hardware
-RTEMS Targets are grouped by architectures and within an architecture there are
+RTEMS targets are grouped by architectures and within an architecture there are
a number of Board Support Packages or BPSs. An architecture is a specific class
or family of processors and can be large such as ARM or specific such as the
NIOS-II or Microblaze.
diff --git a/user/index.rst b/user/index.rst
index b61942e..31895b4 100644
--- a/user/index.rst
+++ b/user/index.rst
@@ -12,8 +12,8 @@ RTEMS User Manual (|version|).
| © 2018 Marçal Comajoan Cara
| © 2018 Vidushi Vashishth
| © 2017 Tanu Hari Dixit
- | © 2016, 2017 embedded brains GmbH
- | © 2016, 2017 Sebastian Huber
+ | © 2016, 2019 embedded brains GmbH
+ | © 2016, 2019 Sebastian Huber
| © 2012, 2015 Chris Johns
| © 1988, 2018 On-Line Applications Research Corporation (OAR)
--
2.13.7
From bb60c0e1105f4dc57f1ab2c913c77f438ff43e39 Mon Sep 17 00:00:00 2001
From: Sebastian Huber <sebastian.hu...@embedded-brains.de>
Date: Fri, 11 Jan 2019 15:28:57 +0100
Subject: [PATCH 5/6] user: Move "Prefixes" to "Quick Start"
Move "Project Sandboxing" to a separate section of the "Installation"
chapter since this is an advance topic which may confuse new users.
---
user/installation/index.rst | 2 +-
...fixes-sandboxing.rst => project-sandboxing.rst} | 41 -------------------
user/start/index.rst | 9 +++++
user/start/prefixes.rst | 47 ++++++++++++++++++++++
4 files changed, 57 insertions(+), 42 deletions(-)
rename user/installation/{prefixes-sandboxing.rst => project-sandboxing.rst} (61%)
create mode 100644 user/start/prefixes.rst
diff --git a/user/installation/index.rst b/user/installation/index.rst
index 07ccc68..1851bd4 100644
--- a/user/installation/index.rst
+++ b/user/installation/index.rst
@@ -45,7 +45,7 @@ repositories for the tools and kernel.
.. toctree::
- prefixes-sandboxing
releases
developer
kernel
+ project-sandboxing
diff --git a/user/installation/prefixes-sandboxing.rst b/user/installation/project-sandboxing.rst
similarity index 61%
rename from user/installation/prefixes-sandboxing.rst
rename to user/installation/project-sandboxing.rst
index 0dd0589..2c5e508 100644
--- a/user/installation/prefixes-sandboxing.rst
+++ b/user/installation/project-sandboxing.rst
@@ -5,47 +5,6 @@
.. index:: Prefixes
.. _prefixes:
-Prefixes
-========
-
-You will see the term :ref:term:`prefix` referred to thoughout 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`.
-
.. _project-sandboxing:
Project Sandboxing
diff --git a/user/start/index.rst b/user/start/index.rst
index 9bcd967..019817f 100644
--- a/user/start/index.rst
+++ b/user/start/index.rst
@@ -9,6 +9,15 @@
Quick Start
***********
+Follow the sections of this chapter step by step to get started developing
+applications on top of RTEMS.
+
+.. toctree::
+ :maxdepth: 5
+ :numbered:
+
+ prefixes
+
The following is a quick start guide that provides a basic set of commands to
build the RTEMS Tools and Kernel. The quick start guide provides links to the
detailed sections if any problems are encountered.
diff --git a/user/start/prefixes.rst b/user/start/prefixes.rst
new file mode 100644
index 0000000..e9dad29
--- /dev/null
+++ b/user/start/prefixes.rst
@@ -0,0 +1,47 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2016 Chris Johns <chr...@rtems.org>
+
+.. index:: prefix
+.. _prefixes:
+
+Prefixes
+========
+
+You will see the term :ref:term:`prefix` referred to thoughout 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`.
--
2.13.7
From 4da18400a98e717ce8d76f6340a78a4006f01879 Mon Sep 17 00:00:00 2001
From: Sebastian Huber <sebastian.hu...@embedded-brains.de>
Date: Fri, 11 Jan 2019 15:55:37 +0100
Subject: [PATCH 6/6] user: Add "Host Computer Setup" to "Quick Start"
---
user/start/host.rst | 19 +++++++++++++++++++
user/start/index.rst | 1 +
2 files changed, 20 insertions(+)
create mode 100644 user/start/host.rst
diff --git a/user/start/host.rst b/user/start/host.rst
new file mode 100644
index 0000000..1437290
--- /dev/null
+++ b/user/start/host.rst
@@ -0,0 +1,19 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2019 embedded brains GmbH
+.. Copyright (C) 2019 Sebastian Huber
+
+.. _QuickStartHost:
+
+Host Computer Setup
+===================
+
+The *host computer* is the thing you use to develop applications. It runs all
+your tools, editors, documentation viewers, etc. To get started with RTEMS
+development you need other tools. This includes a native C, C++ and Python
+development environment. Please make sure that you can build native C/C++
+applications on your host computer. You must be able to build native Python C
+modules. Usually you have to install a Python development package for this.
+Please have a look at the :ref:`Host Computer <host-computer>` chapter for the
+glory details. In particular :ref:`Microsoft Windows <microsoft-windows>` user
+should do this.
diff --git a/user/start/index.rst b/user/start/index.rst
index 019817f..da03fa8 100644
--- a/user/start/index.rst
+++ b/user/start/index.rst
@@ -16,6 +16,7 @@ applications on top of RTEMS.
:maxdepth: 5
:numbered:
+ host
prefixes
The following is a quick start guide that provides a basic set of commands to
--
2.13.7
_______________________________________________
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel
