Changeset 86518bd in rtems-docs


Ignore:
Timestamp:
Jul 4, 2016, 2:30:09 AM (4 years ago)
Author:
Chris Johns <chrisj@…>
Branches:
4.11, master
Children:
f92357f
Parents:
6d7a4d2
Message:

Reorganisse the User Manual to make it easier to navigate.

Location:
user
Files:
7 added
1 deleted
7 edited
4 moved

Legend:

Unmodified
Added
Removed
  • user/conf.py

    r6d7a4d2 r86518bd  
    1111exclude_patterns = ['config/build.rst',
    1212                    'config/runtime.rst',
     13
     14                    'start/installation.rst',
    1315                    'start/basics.rst',
    1416                    'start/depend.rst',
     17                    'start/quick.rst',
     18
    1519                    'start/transition.rst',
    16                     'start/releases.rst',
    17                     'start/development.rst',
    18                     'start/installation.rst',
    19                     'start/windows.rst',
     20
     21                    'hosts/os.rst',
     22                    'hosts/prefixes.rst',
     23                    'hosts/macos.rst',
     24                    'hosts/posix.rst',
     25                    'hosts/windows.rst',
     26
     27                    'installation/prefixes-sandboxing.rst',
     28                    'installation/releases.rst',
     29                    'installation/developer.rst',
     30
     31                    'tools/build.rst',
     32                    'tools/simulation.rst',
     33
    2034                    'test/create.rst',
    2135                    'test/running.rst',
    22                     'tools/build.rst',
    23                     'tools/simulation.rst',
     36
    2437                    'waf/index.rst']
    2538
  • user/glossary/index.rst

    r6d7a4d2 r86518bd  
    11.. comment SPDX-License-Identifier: CC-BY-SA-4.0
    22
    3 
    4 .. _glossary:
    53
    64Glossary
  • user/hosts/windows.rst

    r6d7a4d2 r86518bd  
    44.. comment: All rights reserved.
    55
    6 .. _development-hosts:
    7 
    8 Development Hosts
    9 =================
    10 .. index:: Hosts
    11 
    12 RTEMS applications are developed using cross-development tools running on a
    13 host computer, typically your desktop or a special build server. All RTEMS
    14 tools and runtime libraries are built from source on your host machine. The
    15 RTEMS Project does not maintain binary builds of the tools. This may appear be
    16 the opposite to what you normally experience with host operating systems, and
    17 it is, however this approach works well. RTEMS is not a host operating system
    18 and it is not a distrbution. Providing binary packages for every possible host
    19 operating system is too big a task for the RTEMS Project and it is not a good
    20 use of core developer time. Their time is better spent making RTEMS better and
    21 faster.
    22 
    23 Developer Computer
    24 ------------------
    25 
    26 The rule for selecting a computer for a developer is `more is better` but we do
    27 understand there are limits. Projects set up different configurations and what
    28 is described here is not an approved set up, rather it is a guide. Some
    29 projects have a suitable development machine per developer while others set up
    30 a tightly controlled central build server. RTEMS is flexible and lets you
    31 engineer a development environment that suites you. The basic specs are:
    32 
    33 - Multicore processor
    34 - 8G bytes RAM
    35 - 256G harddisk
    36 
    37 RTEMS makes no demands on graphics.
    38 
    39 If you are using a VM or your host computer is not a fast modern machine do not
    40 be concerned. The tools may take longer to build than faster hardware however
    41 building tools is something you do once. Once the tools and RTEMS is built all
    42 your time can be spent writing and developing your application. Over an hour
    43 does happen and for the ARM architecture with all BSPs it can be many hours.
    44 
    45 Host Software
    46 -------------
    47 
    48 A wide range of host operating systems and hardware can be used. The host
    49 operating systems supported are:
    50 
    51 - Linux
    52 - FreeBSD
    53 - NetBSD
    54 - Apple OS X
    55 - Windows
    56 - Solaris
    57 
    58 The functionality on a POSIX operating such as Linux and FreeBSD is similar and
    59 most features on Windows are supported but you are best to ask on the
    60 :r:list:`users` if you have a specific question.
    61 
    62 We recommend you maintain your operating system by installing any updates.
    63 
    64 POSIX Hosts
    65 -----------
    66 
    67 .. sidebar:: *GDB and Python*
    68 
    69    RTEMS uses Python in GDB to aid debugging which means GDB needs to be built
    70    with Python development libraries. Please check the RSB documentation and
    71    install the packages specified for your host. Make sure a python development
    72    package is included.
    73 
    74 POSIX hosts are most Unix operating systems such as Linux, FreeBSD and
    75 NetBSD. RTEMS development works well on Unix and can scale from a single user
    76 and a desktop machine to a team with decentralised or centralised development
    77 infrastructure. The RTEMS project provides you with the development tools and
    78 aids to help you create an environment that matches your project's needs. The
    79 RTEMS Project's aim is to give you complete freedom to decide on the languages
    80 used in your project, which version control system, and the build system for
    81 your application.
    82 
    83 The following are a few ways you can set up a suitable environment. You are not
    84 limited to what is present here. A common factor that defines the final
    85 location of tools and projects is the place you have suitable storage. The
    86 following set ups assume suitable disk space and disk performance.
    87 
    88 Administrator Access
    89 ~~~~~~~~~~~~~~~~~~~~
    90 
    91 You either have ``root`` access to your host development machine or you do
    92 not. Some users are given hardware that is centrally managed. If you do not
    93 have ``root`` access you can create your work environment in your home
    94 directory. You could use a prefix of :file:`$HOME/development/rtems` or
    95 :file:`$HOME/rtems`. Note, the ``$HOME`` environment variable can be
    96 substituted with ``~``.
    97 
    98 RTEMS Tools and packages do not require ``root`` access
    99 to be built and we encourage you to not build the tools as ``root``. If you
    100 need to control write access then it is best to manage this with groups
    101 assigned to users.
    102 
    103 If you have ``root`` access you can decide to install the tools under any
    104 suitable prefix. This may depend on the hardware in your host development
    105 machine. If the machine is a centralised build server the prefix may be used to
    106 separate production versions from the test versions and as just discussed the
    107 prefix paths may have restricted access rights to only those who manage and
    108 have configuration control of the machine.
    109 
    110 Apple OS X
    111 ----------
    112 
    113 Apple's OS X is fully supported. You need to download and install a recent
    114 version of the Apple developer application Xcode. Xocde is available in the App
    115 Store. Make sure you install the Command Line Tools add on available for
    116 download within Xcode and once installed open a Terminal shell and enter the
    117 command ``cc`` and accept the license agreement.
    118 
    119 The normal prefix when working on OS X as a user is under your home directory.
    120 Prefixes of :file:`$HOME/development/rtems` or :file:`$HOME/rtems` are
    121 suitable.
    122 
    1236.. _microsoft-windows:
    1247
    1258Microsoft Windows
    126 -----------------
     9~~~~~~~~~~~~~~~~~
    12710
    12811RTEMS supports Windows as a development host and the tools for most
     
    16144.. _windows-path-length:
    16245
    163 Path Length
    164 ~~~~~~~~~~~
     46Windows Path Length
     47^^^^^^^^^^^^^^^^^^^
    16548
    16649Windows path length is limited and can cause problems when building the
     
    17962
    18063Parallel Builds with Make
    181 ~~~~~~~~~~~~~~~~~~~~~~~~~
     64^^^^^^^^^^^^^^^^^^^^^^^^^
    18265
    18366The MSYS2 GNU ``make`` has problems when using the `jobs` option. The RSB
     
    18770
    18871POSIX Support
    189 ~~~~~~~~~~~~~
     72^^^^^^^^^^^^^
    19073
    19174Building the RTEMS compilers, debugger, the RTEMS kernel and a number of other
     
    20588
    20689Python
    207 ~~~~~~
     90^^^^^^
    20891
    20992We need Python to build the tools as the RSB is written in Python and we need
     
    21598We cannot use the Python executables created by the Python project (python.org)
    21699as they are built by Microsoft's C (MSC) compiler. Linking the MSC Python
    217 libraries with the MinGW64 executables is not easy and MSYS provided us with a
     100libraries with the MinGW64 executables is not easy and MSYS provides us with a
    218101simple solution so we do not support linking MSC libraries.
    219102
    220 MSYS2 provides two types and versions of Python executables, MinGW and MSYS and
    221 Python version 2 and 3. For Windows we need the MinGW executable so we have
     103MSYS2 provides two types and two versions of Python executables, MinGW and MSYS
     104and Python version 2 and 3. For Windows we need the MinGW executable so we have
    222105suitables libraries and we have to have Python version 2 because on Windows GDB
    223106only builds with Python2.
     
    228111generate.
    229112
     113.. _microsoft-windows-installation:
     114
    230115Installing MSYS2
    231 ~~~~~~~~~~~~~~~~
     116^^^^^^^^^^^^^^^^
    232117
    233118MSYS2 is installed on a new machine using the MSYS2 installer found on
     
    268153.. note::
    269154
    270 The actual output provided may vary due to changes in the dependent packages or
    271 newer package versions.
     155  The actual output provided may vary due to changes in the dependent packages
     156  or newer package versions.
    272157
    273158Install the packages using ``pacman``:
  • user/index.rst

    r6d7a4d2 r86518bd  
    11.. comment SPDX-License-Identifier: CC-BY-SA-4.0
     2
     3.. comment Headingd
     4.. comment  1  ======
     5.. comment  2  ------
     6.. comment  3  ~~~~~~
     7.. comment  4  ^^^^^^
    28
    39.. highlight:: c
     
    1521
    1622        overview/index
     23        ecosys/index
    1724
    1825        start/index
    19         config/index
    20 
    21         tools/index
    22         test/index
     26        hosts/index
     27        installation/index
    2328
    2429        architecture/index
  • user/installation/developer.rst

    r6d7a4d2 r86518bd  
    44.. comment: All rights reserved.
    55
    6 .. _microsoft-windows-installation:
    7 
    8 Microsoft Windows
    9 -----------------
     6.. _developer:
     7.. _development-version:
     8.. _unstable:
     9
     10Developer (Unstable)
     11--------------------
     12.. index:: Git
     13
     14RTEMS provides open access to it's development processes. We call this the
     15developer set up.  The project encouages all users to inspect, review, comment
     16and contribute to the code base. The processes described here are the same
     17processes the core development team use when developing and maintaining RTEMS.
     18
     19.. warning::
     20
     21   The development version is not for use in production and it can break from
     22   time to time.
     23
     24Please read :ref:`development-host` before continuing. The following procedure
     25assumes you have installed and configured your host operating system. It also
     26assumes you have installed any dependent packages needed when building the
     27tools and the kernel.
     28
     29You need to select a location to build and install the RTEMS Tool chain and
     30RTEMS. Make sure there is plenty of disk space and a fast disk is
     31recommended. Our procedure will document building and installing the tools in a
     32home directory called :file:`development/rtems`. Using a home directory means
     33you can do this without needing to be root. You can also use
     34:file:`/opt/rtems/build` if you have access to that path.
     35
     36The location used to install the tools and kernel is called the `prefix`. It is
     37best to have a `prefix` for each different version of RTEMS you are using. If
     38you are using RTEMS 4.11 in production it is not a good idea to install a
     39development version of 4.12 over the top. A separate `prefix` for each version
     40avoids this.
     41
     42The RTEMS tool chain changes less often than the RTEMS kernel. One method of
     43working with development releases is to have a separate `prefix` for the RTEMS
     44tools and a different one for the RTEMS kernel. You can then update each
     45without interacting with the other. You can also have a number of RTEMS
     46versions available to test with.
     47
     48.. sidebar:: *Downloading the source*
     49
     50  You need an internet connection to download the source. The downloaded source
     51  is cached locally and the RSB checksums it. If you run a build again the
     52  download output will be missing. Using the RSB from git will download the
     53  source from the upstream project's home site and this could be `http`, `ftp`,
     54  or `git`.
     55
     56.. _posix-host-tools-chain:
     57.. _macos-host-tools-chain:
     58
     59POSIX and OS X Host Tools Chain
     60~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     61
     62This procedure will build a SPARC tool chain.
     63
     64Clone the RTEMS Source Builder (RSB) repository:
     65
     66.. code-block:: shell
     67
     68  $ cd
     69  $ mkdir -p development/rtems
     70  $ cd development/rtems
     71  $ git clone git://git.rtems.org/rtems-source-builder.git rsb
     72  Cloning into 'rsb'...
     73  remote: Counting objects: 5837, done.
     74  remote: Compressing objects: 100% (2304/2304), done.
     75  remote: Total 5837 (delta 4014), reused 5056 (delta 3494)
     76  Receiving objects: 100% (5837/5837), 2.48 MiB | 292.00 KiB/s, done.
     77  Resolving deltas: 100% (4014/4014), done.
     78  Checking connectivity... done.
     79
     80Check all the host packages you need are present. Current libraries are not
     81checked and this includes checking for the python development libraries GDB
     82requires:
     83
     84.. code-block:: shell
     85
     86  $ cd rsb
     87  $ ./source-builder/sb-check
     88  RTEMS Source Builder - Check, 4.12 (e645642255cc)
     89  Environment is ok
     90
     91Build a tool chain for the SPARC architecure. We are using the SPARC
     92architecture because GDB has a good simulator that lets us run and test the
     93samples RTEMS builds by default. The current development version
     94is `4.12` and is on master:
     95
     96.. code-block:: shell
     97
     98  $ cd rtems
     99  $ ../source-builder/sb-set-builder \
     100      --prefix=/usr/home/chris/development/rtems/4.12 4.12/rtems-sparc
     101  RTEMS Source Builder - Set Builder, 4.12 (e645642255cc)
     102  Build Set: 4.12/rtems-sparc
     103  Build Set: 4.12/rtems-autotools.bset
     104  Build Set: 4.12/rtems-autotools-internal.bset
     105  config: tools/rtems-autoconf-2.69-1.cfg
     106  package: autoconf-2.69-x86_64-linux-gnu-1
     107  Creating source directory: sources
     108  download: ftp://ftp.gnu.org/gnu/autoconf/autoconf-2.69.tar.gz -> sources/autoconf-2.69.tar.gz
     109  downloading: sources/autoconf-2.69.tar.gz - 1.8MB of 1.8MB (100%)
     110  building: autoconf-2.69-x86_64-linux-gnu-1
     111  config: tools/rtems-automake-1.12.6-1.cfg
     112  package: automake-1.12.6-x86_64-linux-gnu-1
     113  download: ftp://ftp.gnu.org/gnu/automake/automake-1.12.6.tar.gz -> sources/automake-1.12.6.tar.gz
     114  downloading: sources/automake-1.12.6.tar.gz - 2.0MB of 2.0MB (100%)
     115  Creating source directory: patches
     116  download: https://git.rtems.org/rtems-tools/plain/tools/4.12/automake/automake-1.12.6-bugzilla.redhat.com-1239379.diff -> patches/automake-1.12.6-bugzilla.redhat.com-1239379.diff
     117  downloading: patches/automake-1.12.6-bugzilla.redhat.com-1239379.diff - 408.0 bytes of 408.0 bytes (100%)
     118  building: automake-1.12.6-x86_64-linux-gnu-1
     119  cleaning: autoconf-2.69-x86_64-linux-gnu-1
     120  cleaning: automake-1.12.6-x86_64-linux-gnu-1
     121  Build Set: Time 0:00:17.465024
     122  Build Set: 4.12/rtems-autotools-base.bset
     123  config: tools/rtems-autoconf-2.69-1.cfg
     124  package: autoconf-2.69-x86_64-linux-gnu-1
     125  building: autoconf-2.69-x86_64-linux-gnu-1
     126  reporting: tools/rtems-autoconf-2.69-1.cfg -> autoconf-2.69-x86_64-linux-gnu-1.txt
     127  reporting: tools/rtems-autoconf-2.69-1.cfg -> autoconf-2.69-x86_64-linux-gnu-1.xml
     128  config: tools/rtems-automake-1.12.6-1.cfg
     129  package: automake-1.12.6-x86_64-linux-gnu-1
     130  building: automake-1.12.6-x86_64-linux-gnu-1
     131  reporting: tools/rtems-automake-1.12.6-1.cfg -> automake-1.12.6-x86_64-linux-gnu-1.txt
     132  reporting: tools/rtems-automake-1.12.6-1.cfg -> automake-1.12.6-x86_64-linux-gnu-1.xml
     133  installing: autoconf-2.69-x86_64-linux-gnu-1 -> /usr/home/chris/development/rtems/4.12
     134  installing: automake-1.12.6-x86_64-linux-gnu-1 -> /usr/home/chris/development/rtems/4.12
     135  cleaning: autoconf-2.69-x86_64-linux-gnu-1
     136  cleaning: automake-1.12.6-x86_64-linux-gnu-1
     137  Build Set: Time 0:00:05.358624
     138  Build Set: Time 0:00:22.824422
     139  config: devel/expat-2.1.0-1.cfg
     140  package: expat-2.1.0-x86_64-linux-gnu-1
     141  download: http://downloads.sourceforge.net/project/expat/expat/2.1.0/expat-2.1.0.tar.gz -> sources/expat-2.1.0.tar.gz
     142    redirect: http://internode.dl.sourceforge.net/project/expat/expat/2.1.0/expat-2.1.0.tar.gz
     143  downloading: sources/expat-2.1.0.tar.gz - 549.4kB of 549.4kB (100%)
     144  building: expat-2.1.0-x86_64-linux-gnu-1
     145  reporting: devel/expat-2.1.0-1.cfg -> expat-2.1.0-x86_64-linux-gnu-1.txt
     146  reporting: devel/expat-2.1.0-1.cfg -> expat-2.1.0-x86_64-linux-gnu-1.xml
     147  config: tools/rtems-binutils-2.26-1.cfg
     148  package: sparc-rtems4.12-binutils-2.26-x86_64-linux-gnu-1
     149  download: ftp://ftp.gnu.org/gnu/binutils/binutils-2.26.tar.bz2 -> sources/binutils-2.26.tar.bz2
     150  downloading: sources/binutils-2.26.tar.bz2 - 24.4MB of 24.4MB (100%)
     151  download: https://git.rtems.org/rtems-tools/plain/tools/4.12/binutils/binutils-2.26-rtems-aarch64-x86_64.patch -> patches/binutils-2.26-rtems-aarch64-x86_64.patch
     152  downloading: patches/binutils-2.26-rtems-aarch64-x86_64.patch - 3.2kB of 3.2kB (100%)
     153  building: sparc-rtems4.12-binutils-2.26-x86_64-linux-gnu-1
     154  reporting: tools/rtems-binutils-2.26-1.cfg -> sparc-rtems4.12-binutils-2.26-x86_64-linux-gnu-1.txt
     155  reporting: tools/rtems-binutils-2.26-1.cfg -> sparc-rtems4.12-binutils-2.26-x86_64-linux-gnu-1.xml
     156  config: tools/rtems-gcc-6-20160228-newlib-2.3.0.20160226-1.cfg
     157  package: sparc-rtems4.12-gcc-6-20160228-newlib-2.3.0.20160226-x86_64-linux-gnu-1
     158  download: ftp://gcc.gnu.org/pub/gcc/snapshots/6-20160228/gcc-6-20160228.tar.bz2 -> sources/gcc-6-20160228.tar.bz2
     159  downloading: sources/gcc-6-20160228.tar.bz2 - 90.8MB of 90.8MB (100%)
     160  download: ftp://sourceware.org/pub/newlib/newlib-2.3.0.20160226.tar.gz -> sources/newlib-2.3.0.20160226.tar.gz
     161  downloading: sources/newlib-2.3.0.20160226.tar.gz - 16.9MB of 16.9MB (100%)
     162  download: http://www.mpfr.org/mpfr-2.4.2/mpfr-2.4.2.tar.bz2 ->
     163  sources/mpfr-2.4.2.tar.bz2
     164  downloading: sources/mpfr-2.4.2.tar.bz2 - 1.0MB of 1.0MB (100%)
     165  download: http://www.multiprecision.org/mpc/download/mpc-0.8.1.tar.gz -> sources/mpc-0.8.1.tar.gz
     166  downloading: sources/mpc-0.8.1.tar.gz - 532.2kB of 532.2kB (100%)
     167  download: ftp://ftp.gnu.org/gnu/gmp/gmp-4.3.2.tar.bz2 -> sources/gmp-4.3.2.tar.bz2
     168  downloading: sources/gmp-4.3.2.tar.bz2 - 1.8MB of 1.8MB (100%)
     169  building: sparc-rtems4.12-gcc-6-20160228-newlib-2.3.0.20160226-x86_64-linux-gnu-1
     170  reporting: tools/rtems-gcc-6-20160228-newlib-2.3.0.20160226-1.cfg -> sparc-rtems4.12-gcc-6-20160228-newlib-2.3.0.20160226-x86_64-linux-gnu-1.txt
     171  reporting: tools/rtems-gcc-6-20160228-newlib-2.3.0.20160226-1.cfg -> sparc-rtems4.12-gcc-6-20160228-newlib-2.3.0.20160226-x86_64-linux-gnu-1.xml
     172  config: tools/rtems-gdb-7.9-1.cfg
     173  package: sparc-rtems4.12-gdb-7.9-x86_64-linux-gnu-1
     174  download: http://ftp.gnu.org/gnu/gdb/gdb-7.9.tar.xz -> sources/gdb-7.9.tar.xz
     175  downloading: sources/gdb-7.9.tar.xz - 17.0MB of 17.0MB (100%)
     176  download: https://git.rtems.org/rtems-tools/plain/tools/4.12/gdb/gdb-sim-arange-inline.diff -> patches/gdb-sim-arange-inline.diff
     177  downloading: patches/gdb-sim-arange-inline.diff - 761.0 bytes of 761.0 bytes (100%)
     178  download: https://git.rtems.org/rtems-tools/plain/tools/4.12/gdb/gdb-sim-cgen-inline.diff -> patches/gdb-sim-cgen-inline.diff
     179  downloading: patches/gdb-sim-cgen-inline.diff - 706.0 bytes of 706.0 bytes (100%)
     180  download: https://git.rtems.org/rtems-tools/plain/tools/4.12/gdb/gdb-7.9-aarch64-x86_64.patch -> patches/gdb-7.9-aarch64-x86_64.patch
     181  downloading: patches/gdb-7.9-aarch64-x86_64.patch - 1.7kB of 1.7kB (100%)
     182  building: sparc-rtems4.12-gdb-7.9-x86_64-linux-gnu-1
     183  reporting: tools/rtems-gdb-7.9-1.cfg -> sparc-rtems4.12-gdb-7.9-x86_64-linux-gnu-1.txt
     184  reporting: tools/rtems-gdb-7.9-1.cfg -> sparc-rtems4.12-gdb-7.9-x86_64-linux-gnu-1.xml
     185  config: tools/rtems-tools-4.12-1.cfg
     186  package: rtems-tools-HEAD-1
     187  Creating source directory: sources/git
     188  git: clone: git://git.rtems.org/rtems-tools.git -> sources/git/rtems-tools.git
     189  git: reset: git://git.rtems.org/rtems-tools.git
     190  git: fetch: git://git.rtems.org/rtems-tools.git -> sources/git/rtems-tools.git
     191  git: checkout: git://git.rtems.org/rtems-tools.git => HEAD
     192  git: pull: git://git.rtems.org/rtems-tools.git
     193  building: rtems-tools-HEAD-1
     194  reporting: tools/rtems-tools-4.12-1.cfg -> rtems-tools-HEAD-1.txt
     195  reporting: tools/rtems-tools-4.12-1.cfg -> rtems-tools-HEAD-1.xml
     196  installing: expat-2.1.0-x86_64-linux-gnu-1 -> /usr/home/chris/development/rtems/4.12
     197  installing: sparc-rtems4.12-binutils-2.26-x86_64-linux-gnu-1 -> /usr/home/chris/development/rtems/4.12
     198  installing: sparc-rtems4.12-gcc-6-20160228-newlib-2.3.0.20160226-x86_64-linux-gnu-1 -> /usr/home/chris/development/rtems/4.12
     199  installing: sparc-rtems4.12-gdb-7.9-x86_64-linux-gnu-1 -> /usr/home/chris/development/rtems/4.12
     200  installing: rtems-tools-HEAD-1 -> /usr/home/chris/development/rtems/4.12
     201  cleaning: expat-2.1.0-x86_64-linux-gnu-1
     202  cleaning: sparc-rtems4.12-binutils-2.26-x86_64-linux-gnu-1
     203  cleaning: sparc-rtems4.12-gcc-6-20160228-newlib-2.3.0.20160226-x86_64-linux-gnu-1
     204  cleaning: sparc-rtems4.12-gdb-7.9-x86_64-linux-gnu-1
     205  cleaning: rtems-tools-HEAD-1
     206  Build Set: Time 0:31:09.754219
     207
     208.. _windows-tool-chain:
     209
     210Windows Host Tool Chain
     211~~~~~~~~~~~~~~~~~~~~~~~
    10212.. index:: Microsoft Windows Installation
    11213
     
    22224   the MSYS2 64bit Shell.
    23225
    24 RTEMS Tools
    25 ~~~~~~~~~~~
     226RTEMS Windows Tools
     227^^^^^^^^^^^^^^^^^^^
    26228
    27229Create a workspace for RTEMS using the following shell command:
     
    203405  $
    204406
     407.. _rtems-kernel-install:
     408
    205409Building the Kernel
    206 ~~~~~~~~~~~~~~~~~~~
     410^^^^^^^^^^^^^^^^^^^
    207411
    208412We can now build the RTEMS kernel using the RTEMS tools we have just
     
    467671   /c/opt/rtems/kernel/pc686
    468672  $
    469 
    470 Building the LibBSD
    471 ~~~~~~~~~~~~~~~~~~~
    472 
    473 The RTEMS BSD Library or libBSD as it is also known is a package of FreeBSD code
    474 ported to RTEMS. It provides a number of advantanced services including a
    475 networking stack.
    476 
    477 | This needs to move to a new section and be completed.
  • user/installation/prefixes-sandboxing.rst

    r6d7a4d2 r86518bd  
    77
    88Prefixes
    9 ========
     9--------
     10
     11.. index:: Prefixes
    1012
    1113You will see the term :ref:term:`prefix` referred to thoughout this
     
    4749this is :file:`/c/opt/rtems`.
    4850
    49 .. _project_sandboxing:
     51.. _project-sandboxing:
    5052
    5153Project Sandboxing
    52 ==================
     54------------------
    5355
    5456Project specific sandboxes let you have a number of projects running in
  • user/installation/releases.rst

    r6d7a4d2 r86518bd  
    66.. _released-version:
    77
    8 Released Version
    9 ================
     8Releases
     9--------
    1010.. index:: tarball
    1111.. index:: release
     
    1515older releases is provided using the RTEMS support channels.
    1616
    17 Please read :ref:`development-hosts` before continuing.
    18 
    19 The following procedure assumes you have installed and configured your host
    20 operating. It also assumes you have installed any dependent packages needed
    21 when building the tools and the kernel.
     17Please read :ref:`development-host` before continuing. The following procedure
     18assumes you have installed and configured your host operating. It also assumes
     19you have installed any dependent packages needed when building the tools and
     20the kernel.
    2221
    2322You need to select a location to build and install the RTEMS Tool chain and
    2423RTEMS. Make sure there is plenty of disk space and a fast disk is
    2524recommended. Our procedure will document building and installing the tools in a
    26 home directory called :file:`/opt/rtems`. This path will require root
     25base directory called :file:`/opt/rtems`. This path will require root
    2726access. If you are working on a machine you do not have root access to you can
    28 use a home directory, :ref:`development-version` has more details about
    29 this. If building on Windows use :file:`/c/opt/rtems` to keep the top level
    30 paths as short as possible. :ref:`microsoft-windows-installation` provides more
    31 detail about path lengths on Windows.
     27use a home directory, If building on Windows use :file:`/c/opt/rtems` to keep
     28the top level paths as short as possible. :ref:`windows-path-length` provides
     29more detail about path lengths on Windows.
    3230
    3331The location used to install the tools and kernel is called the
     
    3836build. A separate `prefix` for each version avoids this.
    3937
    40 Released versions of the RSB download all source code for all packages from the
    41 :r:url:`ftp` rather than from the package's home site. Hosting all the source
    42 on the :r:url:`ftp` ensures the source is present for the life of the
    43 release on the :r:url:`ftp`. If there is a problem accessing the RTEMS FTP
    44 the RSB will fall back to the packages home site.
     38Released versions of the RTEMS Source Builder (RSB) downloads all source code
     39for all packages from the :r:url:`ftp` rather than from the package's home
     40site. Hosting all the source on the :r:url:`ftp` ensures the source is present
     41for the life of the release on the :r:url:`ftp`. If there is a problem
     42accessing the RTEMS FTP the RSB will fall back to the packages home site.
    4543
    4644The :r:url:`ftp` is hosted at the Oregon State University's The Open Source Lab
    4745(http://osuosl.org/). This is a nonprofit organization working for the
    48 advancement of open source technologies and RTEMS is very fortunate to hosted
    49 here. It has excellent internet access and performance.
     46advancement of open source technologies and RTEMS is very fortunate to be
     47shosted here. It has excellent internet access and performance.
    5048
    5149.. note:: **Controlling the RTEMS Kernel Build**
     
    6058   speed the build time up for some architectures that have a lot of BSPs.
    6159
    62 RTEMS Tools Chain
    63 -----------------
     60RTEMS Tools and Kernel
     61~~~~~~~~~~~~~~~~~~~~~~
    6462
    6563This procedure will build a SPARC tool chain. Set up a suitable workspace to
     
    283281 cleaning: sparc-rtems4.11-kernel-4.11.0-1
    284282 Build Set: Time 0:19:15.713662
     283
     284You can now build a 3rd party library or an application as defailted in TBD.
  • user/overview/index.rst

    r6d7a4d2 r86518bd  
    11.. comment SPDX-License-Identifier: CC-BY-SA-4.0
    2 
    3 
    4 .. _overview:
    52
    63Overview
     
    96Welcome to the :ref:term:`RTEMS` User Manual.
    107
    11 This document covers all the topics required as a user of RTEMS to use the
    12 RTEMS operating system.
     8This document covers the topics a user of RTEMS needs to be able to install,
     9configure, build and create applications for the RTEMS operating system.
    1310
    1411RTEMS, Real-Time Executive for Multiprocessor Systems, is a real-time executive
    1512(kernel) which provides a high performance environment for embedded
    16 applications including the following features:
     13applications with the following features:
    1714
    1815.. sidebar:: Developers
     
    2017  Developers should look at the :r:url:`devel` for technical information. The
    2118  design and development of RTEMS is located there.
     19
     20- standards based user interfaces
    2221
    2322- multitasking capabilities
     
    3938- high level of user configurability
    4039
     40- open source with a friendly user license
     41
    4142RTEMS provides features found in modern operating systems:
    4243
     
    4950- permanent media such as flash disks, cards and USB devices
    5051
     52- support for various languages
     53
     54- parallel programming language support
     55
    5156Real-time Application Systems
    52 =============================
     57-----------------------------
    5358
    5459Real-time application systems are a special class of computer applications.
     
    8590
    8691Real-time Executive
    87 ===================
     92-------------------
    8893
    8994Fortunately, real-time operating systems, or real-time executives, serve as a
     
    123128standard software components, the time and cost required to develop
    124129sophisticated real-time applications is significantly reduced.
    125 
    126 Open Source
    127 ===========
    128 
    129 RTEMS is an open source operating system and an open source project. As a user,
    130 you have access to all the source code. We encourage you to work with the
    131 source code and integrate the provided processes used to build tools, the
    132 kernel and any 3rd party libraries into your project's configuration management
    133 processes. The RTEMS project is always improving the way it develivers the
    134 kernel to you and so your feedback is important.
    135 
    136 What we used in the RTEMS project to develop and maintain RTEMS does not
    137 dictate what you use to develop and maintain your project. You can, and should,
    138 select the work-flow that best suites the demands of your project and what you
    139 are delivering.
  • user/start/index.rst

    r6d7a4d2 r86518bd  
    44.. comment: All rights reserved.
    55
    6 ===============
    7 Getting Started
    8 ===============
     6Quick Start
     7============
    98
    10 RTEMS is an open source real-time operating system. As a user you have access
    11 to all the source code. This ``Getting Started`` section will show you how you
    12 build the RTEMS compiler tools, kernel and 3rd party libraries from source.
     9The following is a quick start guide that provides a basic set of commands to
     10build the RTEMS Tools and Kernel. The quick start guide provides links to the
     11detailed sections if any problems are encoutnered.
    1312
    14 .. include:: basics.rst
    15 .. include:: depend.rst
    16 .. include:: installation.rst
    17 .. include:: releases.rst
    18 .. include:: development.rst
    19 .. include:: windows.rst
     13The detailed procedure for installing RTEMS can be found in
     14:ref:`installation`.
     15
     16The development host computer needs to be set up for this quick start procedure
     17to complete successfully. :ref:`host-computer` details what is needed for the
     18supported host operating systems. If Windows is being used it is recommended
     19following the procedure in :ref:`microsoft-windows` first.
     20
     21Their are many ways and locations a suitable environment can be set up. A
     22common factor that defines the final location of tools and projects is the
     23place you have suitable storage. :ref:`prefixes` and :ref:`project-sandboxing`
     24provide detailed examples of possible locations and set ups .
     25
     26This procedure installs a developer set up using the RTEMS Git repositories on
     27a Unix (POSIX) or MacOS host. The output from the commands has been removed and
     28replaced with ``...``.
     29
     30Create a workspace, download the RTEMS Source Builder (RSB) and build a tool
     31chain (:ref:`posix-host-tools-chain`):
     32
     33.. code-block:: shell
     34
     35  $ cd
     36  $ mkdir -p development/rtems
     37  $ cd development/rtems
     38  $ git clone git://git.rtems.org/rtems-source-builder.git rsb
     39    ...
     40  $ cd rsb
     41  $ ./source-builder/sb-check
     42    ...
     43  $ cd rtems
     44  $ ../source-builder/sb-set-builder \
     45      --prefix=/usr/home/chris/development/rtems/4.12 4.12/rtems-sparc
     46    ...
     47
     48Build the RTEMS Kernel (:ref:`rtems-kernel-install`) by cloning the repository,
     49running the ``bootstrap`` procecure, building and finally installing the
     50kernel:
     51
     52.. code-block:: shell
     53
     54  $ export PATH=$HOME/development/rtems/4.12/bin:$PATH
     55  $ cd
     56  $ cd development/rtems
     57  $ mkdir kernel
     58  $ cd kernel
     59  $ git clone git://git.rtems.org/rtems.git rtems
     60    ...
     61  $ cd rtems
     62  $ ./bootstrap -c && ./bootstrap -p && \
     63              $HOME/development/rtems/rsb/source-builder/sb-bootstrap
     64    ...
     65  $ cd ..
     66  $ mkdir erc32
     67  $ cd erc32
     68  $ $HOME/development/rtems/kernel/rtems/configure --prefix=$HOME/development/rtems/4.12 \
     69                     --target=sparc-rtems4.12 --enable-rtemsbsp=erc32 --enable-posix
     70    ...
     71  $ make -j 8
     72    ...
     73  $ make install
     74
     75You can now build a 3rd party library or an application.
  • user/support/index.rst

    r6d7a4d2 r86518bd  
    11.. comment SPDX-License-Identifier: CC-BY-SA-4.0
    2 
    3 
    4 .. _support:
    52
    63Support
     
    1310developers mailing list is the default location to send the report.
    1411
    15 
    1612Bug Tracker
    17 ===========
     13-----------
    1814
    1915The bug tracker can be found at the :r:url:`bugs`.
     
    2925
    3026Documentation
    31 =============
     27-------------
    3228
    3329The latest user documentation can always be found at the :r:url:`docs`.
     
    3733
    3834Mailing Lists
    39 =============
     35-------------
    4036
    4137We have several mailing lists for RTEMS users and developers.
     
    6258
    6359IRC
    64 ===
     60---
    6561
    6662RTEMS IRC is available on the Freenode network. See the `Freenode
     
    8581
    8682Developers
    87 ==========
     83----------
    8884
    8985Developers can find help and support on the mailing lists, see
     
    9288Technical documents including design, :r:url:`gsoc`, :r:url:`socis` can be
    9389found on the :r:url:`devel`.
     90
     91Support Services
     92----------------
     93
     94The wider RTEMS community has developers and orgainizations who can provide
     95commercial support services. These services range from training, implementing
     96new features in RTEMS, helping establish a new project environment for a team,
     97to application and system design. The RTEMS Project does not endorse or promote
     98any provider of these services and we recommend you use a search engine to
     99locate a suitable provider. If you are unsrue please contact a provider and see
     100what is available.
     101
     102If you develop a new feature or you have someone do this for you we recommend
     103you have the work submitted to the project and merged. Once accepted into the
     104project the work will be maintained as part of the development process within
     105the project and this is a benefit for.
  • user/tools/index.rst

    r6d7a4d2 r86518bd  
    11.. comment SPDX-License-Identifier: CC-BY-SA-4.0
    22
    3 =====
    4 Tools
    5 =====
     3.. comment: Copyright (c) 2016 Chris Johns <chrisj@rtems.org>
     4.. comment: All rights reserved.
    65
    7 XXX: All about rtems config
     6===========
     7RTEMS Tools
     8===========
    89
    9 
    10 .. include:: build.rst
    11 .. include:: simulation.rst
    12 
     10The RTEMS kernel is cross-compiled on host computers and linked to 3rd party
     11packages and application code and run on target hardware. This section details
     12how to build asuitable cross-compiler and how to use the tools.
Note: See TracChangeset for help on using the changeset viewer.