From c1809d631dc2dc9e30894325680ff9f5396ccff8 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Fri, 12 Oct 2018 13:44:22 -0500 Subject: Merge duplicative RSB Quick Start into Users Guide --- user/ecosys/index.rst | 156 +++++++++++++++++++++++++++++++++++++++++ user/hosts/os.rst | 45 ++++++++++++ user/installation/releases.rst | 7 +- user/start/index.rst | 50 +++++++++---- 4 files changed, 240 insertions(+), 18 deletions(-) (limited to 'user') diff --git a/user/ecosys/index.rst b/user/ecosys/index.rst index 1e9ee12..1ea97df 100644 --- a/user/ecosys/index.rst +++ b/user/ecosys/index.rst @@ -85,3 +85,159 @@ 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/hosts/os.rst b/user/hosts/os.rst index a120ec2..82ff4de 100644 --- a/user/hosts/os.rst +++ b/user/hosts/os.rst @@ -30,3 +30,48 @@ most features on Windows are supported but you are best to ask on the :r:list:`users` if you have a specific question. We recommend you maintain your operating system by installing any updates. + +We also recommend you keep your environment to the bare minimum, +particularly the PATH variable. Using environment variables has been +proven over the years to be difficult to manage in production systems. + +.. warning:: + + The RSB assumes your host is set up and the needed packages are installed + and configured to work. If your host has not been set up please refer to + :ref:`Hosts` and your host's section for packages you need to install. + +.. topic:: Path to use when building applications: + + Do not forget to set the path before you use the tools, for example to + build the RTEMS kernel. + + The RSB by default will install (copy) the executables to a directory tree + under the *prefix* you supply. To use the tools once finished just set your + path to the ``bin`` directory under the *prefix* you use. In the examples + that follow the *prefix* is ``$HOME/development/rtems/4.11`` and is set + using the ``--prefix`` option so the path you need to configure to build + applications can be set with the following in a BASH shell: + + .. code-block:: shell + + $ export PATH=$HOME/development/rtems/4.11/bin:$PATH + + Make sure you place the RTEMS tool path at the front of your path so they + are searched first. RTEMS can provide newer versions of some tools your + operating system provides and placing the RTEMS tools path at the front + means it is searched first and the RTEMS needed versions of the tools are + used. + +.. note:: + + RSB and RTEMS have a matching *git branch* for each version of RTEMS. For + example, if you want to build a toolchain for 4.11, then you should + checkout the 4.11 branch of the RSB: + + .. code-block:: shell + + $ git checkout -t origin/4.11 + + Branches are available for the 4.9, 4.10, and 4.11 versions of RTEMS. + diff --git a/user/installation/releases.rst b/user/installation/releases.rst index c21326d..3860d74 100644 --- a/user/installation/releases.rst +++ b/user/installation/releases.rst @@ -48,8 +48,9 @@ shosted here. It has excellent internet access and performance. .. note:: **Controlling the RTEMS Kernel Build** - Building releases by default builds the RTEMS kernel. To not build the RTEMS - kernel add the ``--without-rtems`` option to the RSB command line. + Building releases by default does not build the RTEMS kernel. To + build the RTEMS kernel add the ``--with-rtems`` option to the RSB + command line. By default all the BSPs for an architecture are built. If you only wish to have a specific BSP built you can specify the BSP list by providing to the @@ -284,4 +285,4 @@ discussed in :ref:`msys2_parallel_builds`. cleaning: sparc-rtems4.11-kernel-4.11.0-1 Build Set: Time 0:19:15.713662 -You can now build a 3rd party library or an application as defailted in TBD. +You can now build a 3rd party library or an application as defaulted in TBD. diff --git a/user/start/index.rst b/user/start/index.rst index f5e72ca..1016678 100644 --- a/user/start/index.rst +++ b/user/start/index.rst @@ -10,27 +10,47 @@ Quick Start 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 encoutnered. +detailed sections if any problems are encountered. -The detailed procedure for installing RTEMS can be found in -:ref:`installation`. +The detailed procedure for installing an RTEMS Workspace and installing +all tools can be found in :ref:`installation`. This includes information +on installation points, developer versions, and the RTEMS kernel. -The development host computer needs to be set up for this quick start procedure -to complete successfully. :ref:`host-computer` details what is needed for the -supported host operating systems. If Windows is being used it is recommended -following the procedure in :ref:`microsoft-windows` first. +The short version of this procedure is as follows +(:ref:`posix-host-tools-chain`): + +#. Create a workspace (:ref:`installation`), + +#. Download the RTEMS Source Builder (RSB), + +#. Build an RTEMS tool chain for a specific target architecture, + +#. Download RTEMS, and then + +#. Build RTEMS for a specific Board Support Package (BSP). + +Each of these steps is described in a section in this guide. + +Creating a Workspace +==================== + +Before beginning, the development host computer needs to be set up for +this quick start procedure to complete successfully. :ref:`host-computer` +details what is needed for the supported host operating systems. If +Windows is being used it is recommended following the procedure in +:ref:`microsoft-windows` first. There are many ways and locations a suitable environment can be set up. A common factor that defines the final location of tools and projects is the -place you have suitable storage. :ref:`Prefixes` and :ref:`project-sandboxing` -provide detailed examples of possible locations and set ups . - -This procedure installs a developer set up using the RTEMS Git repositories on -a Unix (POSIX) or MacOS host. The output from the commands has been removed and -replaced with ``...``. +place you have suitable storage. Another is permissions. There is no +need to become root or the administrator and we recommend you avoid +doing this. You can build and install the tools anywhere on the host's +file system you, as a standard user, have read and write access too. +:ref:`Prefixes` and :ref:`project-sandboxing` provide detailed examples +of possible locations and set ups. -Create a workspace, download the RTEMS Source Builder (RSB) and build a tool -chain (:ref:`posix-host-tools-chain`): +Simple Example +============== .. code-block:: shell -- cgit v1.2.3