From a34c157d08ef2beaf7ff0f6930a0fce5ecf581cb Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Thu, 24 Mar 2016 09:33:29 +1100 Subject: Corrections from Worth Burruss. Many thanks. --- user/glossary/index.rst | 63 ++++++++++++++++++++++++++++++++++++++++------ user/overview/index.rst | 8 +++--- user/start/basics.rst | 8 +++--- user/start/depend.rst | 42 +++++++++++++++---------------- user/start/development.rst | 8 +++--- user/start/index.rst | 7 +++--- user/start/releases.rst | 24 +++++++++++------- user/start/windows.rst | 16 ++++++------ user/support/index.rst | 46 +++++++++++++++++++-------------- 9 files changed, 143 insertions(+), 79 deletions(-) diff --git a/user/glossary/index.rst b/user/glossary/index.rst index 315b7d7..43d18cb 100644 --- a/user/glossary/index.rst +++ b/user/glossary/index.rst @@ -1,16 +1,63 @@ -======== + +.. _glossary: + Glossary ======== .. glossary:: - Waf - Waf build system. For more information see http://www.waf.io/ + Binutils + GNU Binary Utilities such as the assembler ``as``, linker ``ld`` and a + range of other tools used in the development of software. + + DLL + Dynamically Linker Library used on Windows. + + GCC + GNU Compiler Tool chain. It is the GNU C/C++ compiler, binutils and GDB. + + GDB + GNU Debugger + + MinGW + Minimal GNU system for Windows that lets GCC built programs use the + standard Windows operating system DLLs. It lets you build native Windows + programs with the GNU GCC compiler. + + MinGW64 + Minimal GNU system for 64bit Windows. MinGW64 is not the MinGW project. + + MSYS2 + Minimal System 2 is a fork of the MinGW project's MSYS tool and the MinGW + MSYS tool is a fork of Cygwin project. The Cygwin project provides a POSIX + emulation layer for Windows so POSIX software can run on Windows. MSYS is a + minimal version that is just enough to let ``configure`` scripts run. MSYS + has a simplied path structure to make it easier to building native Windows + programs. + + POSIX + Portable Operating System Interface is a standard that lets software be + portable between compliant operating systems. + + prefix + A path used when building a package so all parts of the package reside + under that path. + + RSB + RTEMS Source Builder is part of the RTEMS Tools Project. It builds packages + such as the tools for the RTEMS operating system. + + RTEMS + The Real-Time Executive for Multiprocessor Systems or RTEMS is a open + source fully featured Real Time Operating System or RTOS that supports a + variety of open standard application programming interfaces (API) and + interface standards such as POSIX and BSD sockets. - Test Suite - Testsuite - RTEMS test suite located in the ``testsuites/`` directory. + Test Suite + See Testsuite + Testsuite + RTEMS test suite located in the ``testsuites/`` directory. - RTEMS - The Real-Time Executive for Multiprocessor Systems or RTEMS is a open source fully featured Real Time Operating System or RTOS that supports a variety of open standard application programming interfaces (API) and interface standards such as POSIX and BSD sockets. + Waf + Waf build system. For more information see http://www.waf.io/ diff --git a/user/overview/index.rst b/user/overview/index.rst index ced35bc..bcb2a14 100644 --- a/user/overview/index.rst +++ b/user/overview/index.rst @@ -1,4 +1,6 @@ -========= + +.. _overview: + Overview ========= @@ -34,7 +36,7 @@ applications including the following features: - high level of user configurability -RTEMS provides features found in moderen operating system: +RTEMS provides features found in modern operating systems: - file systems @@ -42,7 +44,7 @@ RTEMS provides features found in moderen operating system: - USB -- perminante media such as flash disks, cards and USB devices +- permanent media such as flash disks, cards and USB devices Real-time Application Systems ============================= diff --git a/user/start/basics.rst b/user/start/basics.rst index 5a6bd4e..fad3e83 100644 --- a/user/start/basics.rst +++ b/user/start/basics.rst @@ -1,12 +1,12 @@ .. comment: Copyright (c) 2016 Chris Johns .. comment: All rights reserved. -.. _prefixs: +.. _prefixes: Prefixes ======== -You will see the term **prefix** referred to though out this documentation and +You will see the term **prefix** referred to thoughout this documentation and in a wide number of software packages you can download from the internet. A **prefix** is a path on your computer a software package is built and installed under. Packages that have a **prefix** will place all parts under the *prefix @@ -45,10 +45,10 @@ Project Sandboxing ================== 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 +parallel with each project in its own sandbox. You simply 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 mounted under :file:`/bd` for *Big +As an example 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. diff --git a/user/start/depend.rst b/user/start/depend.rst index 87ca161..e37cdc7 100644 --- a/user/start/depend.rst +++ b/user/start/depend.rst @@ -26,7 +26,7 @@ understand there are limits. Projects set up different configurations and what is described here is not an approved set up, rather it is a guide. Some projects have a suitable development machine per developer while others set up a tightly controlled central build server. RTEMS is flexible and lets you -engineering a development environment that suites you. The basic specs are: +engineer a development environment that suites you. The basic specs are: - Multicore processor - 8G bytes RAM @@ -34,8 +34,8 @@ engineering a development environment that suites you. The basic specs are: 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 +If you are using a VM or your host computer and is not a fast modern 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. Over an hour does happen and for the ARM architecture with all BSPs it can be many @@ -54,12 +54,11 @@ operating systems supported are: - Windows - Solaris -The functionality on POSIX operating such as Linux and FreeBSD is similar and -most features on Windows are supported but you are best to ask on +The functionality on a POSIX operating such as Linux and FreeBSD is similar and +most features on Windows are supported but you are best to ask on the :r:list:`users` if you have a specific question. -Install and set up your host operating system. We recommend you maintain your -operating system by installing any updates. +We recommend you maintain your operating system by installing any updates. POSIX Hosts ----------- @@ -76,17 +75,17 @@ 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 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. +RTEMS Project's aim is to give you 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 location of tools and projects is the place you have suitable storage. The following set ups assume suitable disk space and disk performance. -Adminisrator Access -~~~~~~~~~~~~~~~~~~~ +Administrator Access +~~~~~~~~~~~~~~~~~~~~ You either have ``root`` access to your host development machine or you do not. Some users are given hardware that is centrally managed. If you do not @@ -96,7 +95,7 @@ directory. You could use a prefix of :file:`$HOME/development/rtems` or substituted with ``~``. RTEMS Tools and packages do not require ``root`` access -to be built and we encourage you do not build the tools as ``root``. If you +to be built and we encourage you to 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. @@ -104,8 +103,8 @@ 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. +prefix paths may have restricted access rights to only those who manage and +have configuration control of the machine. Apple OS X ---------- @@ -143,7 +142,7 @@ complexity as well as a performance over-head. The RTEMS Project uses these POSIX emulation shells to run configure scripts that come with various open source packages such as `gcc` so they form an important and valued part of the environment we describe here. The output of this procedure forms the tools you -use during your application development and they do not depend the emulation +use during your application development and they do not depend on the emulation DLLs. The performance of the compiler is as good as you can have on Windows and the @@ -169,10 +168,11 @@ 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 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 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`. +some of the GNU tools such as those in the ``binutils`` package cannot. + +The release packages of the RSB when unpacked have top level file names that +are too big to build RTEMS. You need to change or rname that path to something +smaller to build. This is indicated in :ref:`released-version`. .. _msys2_parallel_builds: @@ -198,7 +198,7 @@ executables. The shell is a standard Bourne shell and the MSYS2 environment is a stripped Cygwin shell with enough support to run the various ``configure`` scripts needed to build the RTEMS tools and the RTEMS kernel. -MSYS2 is built around the ``pacman`` packing tool. This makes MSYS2 a +MSYS2 is built around the ``pacman`` packaging tool. This makes MSYS2 a distribution and that is a welcome feature on Windows. You get a powerful tool to manage your development environment on Windows. diff --git a/user/start/development.rst b/user/start/development.rst index 45f9f03..9cc7744 100644 --- a/user/start/development.rst +++ b/user/start/development.rst @@ -20,8 +20,8 @@ Please read :ref:`development-hosts` before continuing. time to time. The following procedure assumes you have installed and configured your host -operating. It also assumes you have installed any dependent packages needed -when building the tools and the kernel. +operating system. It also assumes you have installed any dependent packages +needed when building the tools and the kernel. You need to select a location to build and install the RTEMS Tool chain and RTEMS. Make sure there is plenty of disk space and a fast disk is @@ -32,7 +32,7 @@ you can do this without needing to be root. You can also use 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 +you are using RTEMS 4.11 in production it is not a good idea to install a development version of 4.12 over the top. A separate `prefix` for each version avoids this. @@ -590,7 +590,7 @@ When you save and exit the editor git will report the commit's status: 1 file changed, 1 insertion(+), 1 deletion(-) You can either email the patch to :r:list:`devel` with the following git -command: +command, and it is `minus one` on the command line: .. code-block:: shell diff --git a/user/start/index.rst b/user/start/index.rst index eef0024..03432c1 100644 --- a/user/start/index.rst +++ b/user/start/index.rst @@ -5,10 +5,9 @@ Getting Started =============== -RTEMS is an open source operating and an open source project. As a user you -have access to all the source code and this `Getting Started`_ section will show -you how you build the RTEMS compiler tools, kernel and 3rd party libraries from -source. +RTEMS is an open source real-time operating system. As a user you have access +to all the source code and this `Getting Started`_ section will show you how +you build the RTEMS compiler tools, kernel and 3rd party libraries from source. .. include:: basics.rst .. include:: depend.rst diff --git a/user/start/releases.rst b/user/start/releases.rst index 1ae0cfc..c949215 100644 --- a/user/start/releases.rst +++ b/user/start/releases.rst @@ -31,13 +31,20 @@ detail about path lengths on Windows. 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. +using RTEMS 4.11 in production it is **not** a good idea to install a +development version of 4.12 over the top by using the same `prefix` as the 4.11 +build. 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 -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. +Released versions of the RSB download all source code for all packages from the +:r:url:`ftp` rather than from the package's home site. Hosting all the source +on the :r:url:`ftp` ensures the source is present for the life of the +release on the :r:url:`ftp`. If there is a problem accessing the RTEMS FTP +the RSB will fall back to the packages home site. + +The :r:url:`ftp` is hosted at the Oregon State University's The Open Source Lab +(http://osuosl.org/). This is a nonprofit organization working for the +advancement of open source technologies and RTEMS is very fortunate to hosted +here. It has excellent internet access and performance. .. note:: **Controlling the RTEMS Kernel Build** @@ -50,12 +57,11 @@ RTEMS FTP the RSB will fall back to the packages home site. 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. - RTEMS Tools Chain ----------------- -Set up a suitable workspace to build the release in. On Unix: +This procedure will build a SPARC tool chain. Set up a suitable workspace to +build the release in. On Unix: .. code-block:: shell diff --git a/user/start/windows.rst b/user/start/windows.rst index 2f78d5b..34998a9 100644 --- a/user/start/windows.rst +++ b/user/start/windows.rst @@ -83,10 +83,10 @@ Check the RSB has a valid environment: $ To build a set of RTEMS tools for the Intel ``i386`` architecture. The build -runs a single job rather a job per CPU in your machine and will take a long -time so please be patient. The RSB creates a log file containing all the build -output and it will be changing size. The RSB command to build ``i386`` tools -is: +runs a single job rather than a job per CPU in your machine and will take a +long time so please be patient. The RSB creates a log file containing all the +build output and it will be changing size. The RSB command to build ``i386`` +tools is: .. code-block:: shell @@ -323,7 +323,7 @@ Finally we run the RSB's parallel ``bootstrap`` command: We will build the RTEMS kernel for the ``i386`` target and the ``pc686`` BSP. You can check the available BSPs by running the ``rtems-bsps`` command -found in the to directory of the RTEMS kernel source. We build the Board +found in the top directory of the RTEMS kernel source. We build the Board Support Package (BSP) outside the kernel source tree: .. code-block:: shell @@ -468,6 +468,8 @@ Install the kernel to our prefix: Building the LibBSD ~~~~~~~~~~~~~~~~~~~ -The RTEMS BSD Library or libBSD as it is also know is a package of FreeBSD code +The RTEMS BSD Library or libBSD as it is also known is a package of FreeBSD code ported to RTEMS. It provides a number of advantanced services including a -networking stack +networking stack. + +| This needs to move to a new section and be completed. diff --git a/user/support/index.rst b/user/support/index.rst index dc53b0a..adfcd65 100644 --- a/user/support/index.rst +++ b/user/support/index.rst @@ -1,10 +1,14 @@ -======= + +.. _support: + Support ======= RTEMS offers a variety of support options. -This chapter covers all options available to both users and developers. If you belive this is a bug report please submit it to the bug tracker otherwise the developers mailing list the default location. +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 the default location. Bug Tracker @@ -12,18 +16,19 @@ Bug Tracker The bug tracker can be found at the :r:url:`bugs`. -See the `Submission Guidelines `_ 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. +See the `Submission Guidelines `_ 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`. +The latest user documentation can always be found at the :r:url:`docs`. .. _support-mailing-lists: @@ -56,28 +61,31 @@ We have several mailing lists for RTEMS users and developers. IRC === -RTEMS IRC is available on the Freenode network. See the `Freenode `_ web site for details on connecting, selecting a nickname, and general usage tips. If you are new to IRC it is recommended reading. - +RTEMS IRC is available on the Freenode network. See the `Freenode +`_ 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. -Logs - +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 +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. - - +to your search terms. Developers ========== -Developers can find help and support on the mailing lists, see :ref:`support-mailing-lists`. +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`. +Technical documents including design, :r:url:`gsoc`, :r:url:`socis` can be +found on the :r:url:`devel`. -- cgit v1.2.3