Changeset c1809d6 in rtems-docs


Ignore:
Timestamp:
Oct 12, 2018, 6:44:22 PM (6 months ago)
Author:
Joel Sherrill <joel@…>
Branches:
master
Children:
5577cc0
Parents:
d40e66b
git-author:
Joel Sherrill <joel@…> (10/12/18 18:44:22)
git-committer:
Joel Sherrill <joel@…> (10/14/18 01:06:50)
Message:

Merge duplicative RSB Quick Start into Users Guide

Files:
1 added
1 deleted
6 edited

Legend:

Unmodified
Added
Removed
  • rsb/index.rst

    rd40e66b rc1809d6  
    5454
    5555        source-builder
    56         quick-start
     56        building-tools-and-rtems.rst
    5757        hosts
    5858        project-sets
  • rsb/source-builder.rst

    rd40e66b rc1809d6  
    6767
    6868This documentation caters for a range of users from new to experienced RTEMS
    69 developers. New users can follow the Quick Start section up to the "Installing
    70 and Tar Files" to get a working tools and RTEMS. Users building a binary tool
    71 set for release can read the "Installing and Tar Files". Users wanting to run
    72 and test bleeding edge tools or packages, or wanting update or extend the RSB's
     69developers who want to understand the RTEMS Source Builder. New users
     70who just want to build tools should follow the Quick Start section in
     71the User's Guide.  Users building a binary tool set for release can
     72read the "Installing and Tar Files". Users wanting to run and test
     73bleeding edge tools or packages, or wanting update or extend the RSB's
    7374configuration can read the remaining sections.
    7475
     
    155156needed. Rather than start again Chris decided to take the parsing code for the
    156157*spec* file format and build a new tool called the RTEMS Source Builder.
     158
     159Controlling the Tools Build
     160---------------------------
     161
     162Build sets can be controlled via the command line to enable and disable various
     163features. There is no definitive list of build options that can be listed
     164because they are implemented with the configuration scripts. The best way to
     165find what is available is to grep the configuration files. for ``with`` and
     166``without``.
     167
     168Following are currently available:
     169
     170``--without-rtems``
     171  Do not build RTEMS when building an RTEMS build set.
     172
     173``--without-cxx``
     174  Do not build a C++ compiler.
     175
     176``--with-ada``
     177  Attempt to build an Ada compiler.  You need a native GNAT installed.
     178
     179``--with-fortran``
     180  Attempt to build a Fortran compiler.
     181
     182``--with-objc``
     183  Attempt to build a C++ compiler.
     184
     185
  • user/ecosys/index.rst

    rd40e66b rc1809d6  
    8686architecture or BSP. The RTEMS Project encourages users and organizations to
    8787fill this role for the community.
     88
     89Building and Deploying Tool Binaries
     90------------------------------------
     91
     92If you wish to create and distribute your build or you want to archive a build
     93you can create a tar file. We term this deploying a build. This is a more
     94advanced method for binary packaging and installing of tools.
     95
     96By default the RTEMS Source Builder installs the built packages directly and
     97optionally it can also create a *build set tar file* or a *package tar file*
     98per package built. The normal and default behaviour is to let the RTEMS Source
     99Builder install the tools. The source will be downloaded, built, installed and
     100cleaned up.
     101
     102The tar files are created with the full build prefix present and if you follow
     103the examples given in this documentation the path is absolute. This can cause
     104problems if you are installing on a host you do not have super user or
     105administrator rights on because the prefix path may references part you do not
     106have write access too and tar will not extract the files. You can use the
     107``--strip-components`` option in tar if your host tar application supports it
     108to remove the parts you do not have write access too or you may need to unpack
     109the tar file somewhere and copy the file tree from the level you have write
     110access from. Embedding the full prefix path in the tar files lets you know what
     111the prefix is and is recommended. For example if
     112``/home/chris/development/rtems/4.11`` is the prefix used you cannot change
     113directory to the root (``/``) and untar the file because the ``/home`` is root
     114access only. To install a tar file you have downloaded into your new machine's
     115``Downloads`` directory in your home directoty you would enter:
     116
     117.. code-block:: shell
     118
     119    $ cd /somewhere
     120    $ tar --strip-components=3 -xjf \
     121          $HOME/Downloads/rtems-4.11-sparc-rtems4.11-1.tar.bz2
     122
     123A build set tar file is created by adding ``--bset-tar-file`` option to the
     124``sb-set-builder`` command::
     125
     126    $ ../source-builder/sb-set-builder --log=l-sparc.txt \
     127             --prefix=$HOME/development/rtems/4.11 \
     128             --bset-tar-file \     <1>
     129             4.11/rtems-sparc
     130    Source Builder - Set Builder, v0.2.0
     131    Build Set: 4.11/rtems-sparc
     132    config: expat-2.1.0-1.cfg
     133    package: expat-2.1.0-x86_64-freebsd9.1-1
     134    building: expat-2.1.0-x86_64-freebsd9.1-1
     135    config: tools/rtems-binutils-2.22-1.cfg
     136    package: sparc-rtems4.11-binutils-2.22-1
     137    building: sparc-rtems4.11-binutils-2.22-1
     138    config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg
     139    package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
     140    building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
     141    config: tools/rtems-gdb-7.5.1-1.cfg
     142    package: sparc-rtems4.11-gdb-7.5.1-1
     143    building: sparc-rtems4.11-gdb-7.5.1-1
     144    installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11 <2>
     145    installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
     146    installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
     147    installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
     148    tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2      <3>
     149    cleaning: expat-2.1.0-x86_64-freebsd9.1-1
     150    cleaning: sparc-rtems4.11-binutils-2.22-1
     151    cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
     152    cleaning: sparc-rtems4.11-gdb-7.5.1-1
     153    Build Set: Time 0:15:25.92873
     154
     155.. topic:: Items
     156
     157  1. The option to create a build set tar file.
     158
     159  2. The installation still happens unless you specify ``--no-install``.
     160
     161  3. Creating the build set tar file.
     162
     163You can also suppress installing the files using the ``--no-install``
     164option. This is useful if your prefix is not accessiable, for example when
     165building Canadian cross compiled tool sets::
     166
     167    $ ../source-builder/sb-set-builder --log=l-sparc.txt \
     168                --prefix=$HOME/development/rtems/4.11 \
     169                --bset-tar-file \
     170                --no-install \      <1>
     171                4.11/rtems-sparc
     172    Source Builder - Set Builder, v0.2.0
     173    Build Set: 4.11/rtems-sparc
     174    config: expat-2.1.0-1.cfg
     175    package: expat-2.1.0-x86_64-freebsd9.1-1
     176    building: expat-2.1.0-x86_64-freebsd9.1-1
     177    config: tools/rtems-binutils-2.22-1.cfg
     178    package: sparc-rtems4.11-binutils-2.22-1
     179    building: sparc-rtems4.11-binutils-2.22-1
     180    config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg
     181    package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
     182    building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
     183    config: tools/rtems-gdb-7.5.1-1.cfg
     184    package: sparc-rtems4.11-gdb-7.5.1-1
     185    building: sparc-rtems4.11-gdb-7.5.1-1
     186    tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2    <2>
     187    cleaning: expat-2.1.0-x86_64-freebsd9.1-1
     188    cleaning: sparc-rtems4.11-binutils-2.22-1
     189    cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
     190    cleaning: sparc-rtems4.11-gdb-7.5.1-1
     191    Build Set: Time 0:14:11.721274
     192    $ ls tar
     193    rtems-4.11-sparc-rtems4.11-1.tar.bz2
     194
     195.. topic:: Items
     196
     197  1. The option to supressing installing the packages.
     198
     199  2. Create the build set tar.
     200
     201A package tar file can be created by adding the ``--pkg-tar-files`` to the
     202``sb-set-builder`` command. This creates a tar file per package built in the
     203build set::
     204
     205    $ ../source-builder/sb-set-builder --log=l-sparc.txt \
     206            --prefix=$HOME/development/rtems/4.11 \
     207            --bset-tar-file \
     208            --pkg-tar-files \        <1>
     209            --no-install 4.11/rtems-sparc
     210    Source Builder - Set Builder, v0.2.0
     211    Build Set: 4.11/rtems-sparc
     212    config: expat-2.1.0-1.cfg
     213    package: expat-2.1.0-x86_64-freebsd9.1-1
     214    building: expat-2.1.0-x86_64-freebsd9.1-1
     215    config: tools/rtems-binutils-2.22-1.cfg
     216    package: sparc-rtems4.11-binutils-2.22-1
     217    building: sparc-rtems4.11-binutils-2.22-1
     218    config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg
     219    package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
     220    building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
     221    config: tools/rtems-gdb-7.5.1-1.cfg
     222    package: sparc-rtems4.11-gdb-7.5.1-1
     223    building: sparc-rtems4.11-gdb-7.5.1-1
     224    tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2
     225    cleaning: expat-2.1.0-x86_64-freebsd9.1-1
     226    cleaning: sparc-rtems4.11-binutils-2.22-1
     227    cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
     228    cleaning: sparc-rtems4.11-gdb-7.5.1-1
     229    Build Set: Time 0:14:37.658460
     230    $ ls tar
     231    expat-2.1.0-x86_64-freebsd9.1-1.tar.bz2           sparc-rtems4.11-binutils-2.22-1.tar.bz2
     232    sparc-rtems4.11-gdb-7.5.1-1.tar.bz2 <2>           rtems-4.11-sparc-rtems4.11-1.tar.bz2 <3>
     233    sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1.tar.bz2
     234
     235.. topic:: Items
     236
     237  1. The option to create packages tar files.
     238
     239  2. The GDB package tar file.
     240
     241  3. The build set tar file. All the others in a single tar file.
     242
     243
  • user/hosts/os.rst

    rd40e66b rc1809d6  
    3131
    3232We recommend you maintain your operating system by installing any updates.
     33
     34We also recommend you keep your environment to the bare minimum,
     35particularly the PATH variable. Using environment variables has been
     36proven over the years to be difficult to manage in production systems.
     37
     38.. warning::
     39
     40    The RSB assumes your host is set up and the needed packages are installed
     41    and configured to work. If your host has not been set up please refer to
     42    :ref:`Hosts` and your host's section for packages you need to install.
     43
     44.. topic:: Path to use when building applications:
     45
     46    Do not forget to set the path before you use the tools, for example to
     47    build the RTEMS kernel.
     48
     49    The RSB by default will install (copy) the executables to a directory tree
     50    under the *prefix* you supply. To use the tools once finished just set your
     51    path to the ``bin`` directory under the *prefix* you use. In the examples
     52    that follow the *prefix* is ``$HOME/development/rtems/4.11`` and is set
     53    using the ``--prefix`` option so the path you need to configure to build
     54    applications can be set with the following in a BASH shell:
     55
     56    .. code-block:: shell
     57
     58      $ export PATH=$HOME/development/rtems/4.11/bin:$PATH
     59
     60    Make sure you place the RTEMS tool path at the front of your path so they
     61    are searched first. RTEMS can provide newer versions of some tools your
     62    operating system provides and placing the RTEMS tools path at the front
     63    means it is searched first and the RTEMS needed versions of the tools are
     64    used.
     65
     66.. note::
     67
     68    RSB and RTEMS have a matching *git branch* for each version of RTEMS. For
     69    example, if you want to build a toolchain for 4.11, then you should
     70    checkout the 4.11 branch of the RSB:
     71
     72    .. code-block:: shell
     73
     74      $ git checkout -t origin/4.11
     75
     76    Branches are available for the 4.9, 4.10, and 4.11 versions of RTEMS.
     77
  • user/installation/releases.rst

    rd40e66b rc1809d6  
    4949.. note:: **Controlling the RTEMS Kernel Build**
    5050
    51    Building releases by default builds the RTEMS kernel. To not build the RTEMS
    52    kernel add the ``--without-rtems`` option to the RSB command line.
     51   Building releases by default does not build the RTEMS kernel. To
     52   build the RTEMS kernel add the ``--with-rtems`` option to the RSB
     53   command line.
    5354
    5455   By default all the BSPs for an architecture are built. If you only wish to
     
    285286 Build Set: Time 0:19:15.713662
    286287
    287 You can now build a 3rd party library or an application as defailted in TBD.
     288You can now build a 3rd party library or an application as defaulted in TBD.
  • user/start/index.rst

    rd40e66b rc1809d6  
    1111The following is a quick start guide that provides a basic set of commands to
    1212build the RTEMS Tools and Kernel. The quick start guide provides links to the
    13 detailed sections if any problems are encoutnered.
     13detailed sections if any problems are encountered.
    1414
    15 The detailed procedure for installing RTEMS can be found in
    16 :ref:`installation`.
     15The detailed procedure for installing an RTEMS Workspace and installing
     16all tools can be found in :ref:`installation`. This includes information
     17on installation points, developer versions, and the RTEMS kernel.
    1718
    18 The development host computer needs to be set up for this quick start procedure
    19 to complete successfully. :ref:`host-computer` details what is needed for the
    20 supported host operating systems. If Windows is being used it is recommended
    21 following the procedure in :ref:`microsoft-windows` first.
     19The short version of this procedure is as follows
     20(:ref:`posix-host-tools-chain`):
     21
     22#. Create a workspace (:ref:`installation`),
     23
     24#. Download the RTEMS Source Builder (RSB),
     25
     26#. Build an RTEMS tool chain for a specific target architecture,
     27
     28#. Download RTEMS, and then
     29
     30#. Build RTEMS for a specific Board Support Package (BSP).
     31
     32Each of these steps is described in a section in this guide.
     33
     34Creating a Workspace
     35====================
     36
     37Before beginning, the development host computer needs to be set up for
     38this quick start procedure to complete successfully. :ref:`host-computer`
     39details what is needed for the supported host operating systems. If
     40Windows is being used it is recommended following the procedure in
     41:ref:`microsoft-windows` first.
    2242
    2343There are many ways and locations a suitable environment can be set up. A
    2444common factor that defines the final location of tools and projects is the
    25 place you have suitable storage. :ref:`Prefixes` and :ref:`project-sandboxing`
    26 provide detailed examples of possible locations and set ups .
     45place you have suitable storage. Another is permissions.  There is no
     46need to become root or the administrator and we recommend you avoid
     47doing this. You can build and install the tools anywhere on the host's
     48file system you, as a standard user, have read and write access too.
     49:ref:`Prefixes` and :ref:`project-sandboxing` provide detailed examples
     50of possible locations and set ups.
    2751
    28 This procedure installs a developer set up using the RTEMS Git repositories on
    29 a Unix (POSIX) or MacOS host. The output from the commands has been removed and
    30 replaced with ``...``.
    31 
    32 Create a workspace, download the RTEMS Source Builder (RSB) and build a tool
    33 chain (:ref:`posix-host-tools-chain`):
     52Simple Example
     53==============
    3454
    3555.. code-block:: shell
Note: See TracChangeset for help on using the changeset viewer.