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 --- rsb/building-tools-and-rtems.rst | 38 +++ rsb/index.rst | 2 +- rsb/quick-start.rst | 535 --------------------------------------- rsb/source-builder.rst | 37 ++- user/ecosys/index.rst | 156 ++++++++++++ user/hosts/os.rst | 45 ++++ user/installation/releases.rst | 7 +- user/start/index.rst | 50 ++-- 8 files changed, 312 insertions(+), 558 deletions(-) create mode 100644 rsb/building-tools-and-rtems.rst delete mode 100644 rsb/quick-start.rst diff --git a/rsb/building-tools-and-rtems.rst b/rsb/building-tools-and-rtems.rst new file mode 100644 index 0000000..5fd5d78 --- /dev/null +++ b/rsb/building-tools-and-rtems.rst @@ -0,0 +1,38 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. comment COPYRIGHT (c) 2012 - 2016, 2018. +.. comment Chris Johns + +Building Tools and RTEMS +======================== + +The Quick Start section of the RTEMS Users Guide covers the typical +information and process needed to build both an RTEMS toolset and +RTEMS itself. This section has information on specific configuration +options that may be needed. + +Controlling the Build +--------------------- + +Build sets can be controlled via the command line to enable and disable various +features. There is no definitive list of build options that can be listed +because they are implemented with the configuration scripts. The best way to +find what is available is to grep the configuration files. for ``with`` and +``without``. + +Following are currently available: + +``--without-rtems`` + Do not build RTEMS when building an RTEMS build set. + +``--without-cxx`` + Do not build a C++ compiler. + +``--with-ada`` + Attempt to build an Ada compiler. You need a native GNAT installed. + +``--with-fortran`` + Attempt to build a Fortran compiler. + +``--with-objc`` + Attempt to build a C++ compiler. diff --git a/rsb/index.rst b/rsb/index.rst index 7b64945..36e0883 100644 --- a/rsb/index.rst +++ b/rsb/index.rst @@ -53,7 +53,7 @@ Table of Contents :numbered: source-builder - quick-start + building-tools-and-rtems.rst hosts project-sets cross-canadian-cross diff --git a/rsb/quick-start.rst b/rsb/quick-start.rst deleted file mode 100644 index 16102f7..0000000 --- a/rsb/quick-start.rst +++ /dev/null @@ -1,535 +0,0 @@ -.. comment SPDX-License-Identifier: CC-BY-SA-4.0 - -.. comment COPYRIGHT (c) 2012 - 2016. -.. comment Chris Johns - -Quick Start -=========== - -The quick start will show you how to build a set of RTEMS tools for a supported -architecture. The tools are installed into a build *prefix*. The *prefix* is the -top of a group of directories containing all the files needed to develop RTEMS -applications. Building an RTEMS build set will build all that you need. This -includes autoconf, automake, assemblers, linkers, compilers, debuggers, -standard libraries and RTEMS itself. - -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. I recommend you use your home directory and work under the directory -``~/development/rtems``. The examples shown here will do this. - -You can use the build *prefix* to install and maintain different versions of -the tools. Doing this lets you try a new set of tools while not touching your -proven working production set of tools. Once you have proven the new tools are -working rebuild with the *production* prefix switching your development to them. - -We 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. - -Setup ------ - -Setup a development work space:: - - $ cd - $ mkdir -p development/rtems/src - $ cd development/rtems/src - -The RTEMS Source Builder is distributed as source. It is Python code so all you -need to do is download the release's RSB tarball or clone the code directly -from the RTEMS GIT repository:: - - $ git clone git://git.rtems.org/rtems-source-builder.git - $ cd rtems-source-builder - -.. topic:: Workspaces - - The examples in the *Quick Start Guide* build and install tools in your - *home* directory. Please refer to the RTEMS User Manual for more detail - about *Sandboxing* and the *prefix*. - -Checking --------- - -The next step is to check if your host is set up correctly. The RTEMS Source -Builder provides a tool to help:: - - $ source-builder/sb-check - warning: exe: absolute exe found in path: (__objcopy) /usr/local/bin/objcopy <1> - warning: exe: absolute exe found in path: (__objdump) /usr/local/bin/objdump - error: exe: not found: (_xz) /usr/local/bin/xz <2> - RTEMS Source Builder environment is not correctly set up - $ source-builder/sb-check - RTEMS Source Builder environment is ok <3> - -.. topic:: Items: - - 1. A tool is in the environment path but it does not match the expected path. - - 2. The executable ``xz`` is not found. - - 3. The host's environment is set up correct. - -The checking tool will output a list of executable files not found if problems -are detected. Locate those executable files and install them. You may also be -given a list of warnings about executable files not in the expected location -however the executable was located somewhere in your environment's path. You -will need to check each tool to determine if this is an issue. An executable -not in the standard location may indicate it is not the host operating system's -standard tool. It maybe ok or it could be buggy, only you can determine this. - -The :ref:`Hosts` section lists packages you should install for common host -operating systems. It maybe worth checking if you have those installed. - -Build Sets ----------- - -The RTEMS tools can be built within the RTEMS Source Builder's source tree. We -recommend you do this so lets change into the RTEMS directory in the RTEMS -Source Builder package:: - - $ cd rtems - -If you are unsure how to specify the build set for the architecture you wish to -build ask the tool:: - - $ ../source-builder/sb-set-builder --list-bsets <1> - RTEMS Source Builder - Set Builder, v4.11.0 - Examining: config - Examining: ../source-builder/config <2> - 4.10/rtems-all.bset <3> - 4.10/rtems-arm.bset <4> - 4.10/rtems-autotools.bset - 4.10/rtems-avr.bset - 4.10/rtems-bfin.bset - 4.10/rtems-h8300.bset - 4.10/rtems-i386.bset - 4.10/rtems-lm32.bset - 4.10/rtems-m32c.bset - 4.10/rtems-m32r.bset - 4.10/rtems-m68k.bset - 4.10/rtems-mips.bset - 4.10/rtems-nios2.bset - 4.10/rtems-powerpc.bset - 4.10/rtems-sh.bset - 4.10/rtems-sparc.bset - 4.11/rtems-all.bset - 4.11/rtems-arm.bset - 4.11/rtems-autotools.bset - 4.11/rtems-avr.bset - 4.11/rtems-bfin.bset - 4.11/rtems-h8300.bset - 4.11/rtems-i386.bset - 4.11/rtems-lm32.bset - 4.11/rtems-m32c.bset - 4.11/rtems-m32r.bset - 4.11/rtems-m68k.bset - 4.11/rtems-microblaze.bset - 4.11/rtems-mips.bset - 4.11/rtems-moxie.bset - 4.11/rtems-nios2.bset - 4.11/rtems-powerpc.bset - 4.11/rtems-sh.bset - 4.11/rtems-sparc.bset - 4.11/rtems-sparc64.bset - 4.11/rtems-v850.bset - 4.9/rtems-all.bset - 4.9/rtems-arm.bset - 4.9/rtems-autotools.bset - 4.9/rtems-i386.bset - 4.9/rtems-m68k.bset - 4.9/rtems-mips.bset - 4.9/rtems-powerpc.bset - 4.9/rtems-sparc.bset - gnu-tools-4.6.bset - rtems-4.10-base.bset <5> - rtems-4.11-base.bset - rtems-4.9-base.bset - rtems-base.bset <5> - -.. topic:: Items: - - 1. Only option required is ``--list-bsets`` - - 2. The paths inspected. See :ref:`Configuration`. - - 3. A build set to build all RTEMS 4.10 supported architectures. - - 4. The build set for the ARM architecture on RTEMS 4.10. - - 5. Support build set file with common functionality included by other build - set files. - -Building --------- - -The quick start builds a SPARC tool set:: - - $ ../source-builder/sb-set-builder --log=l-sparc.txt \ <1> - --prefix=$HOME/development/rtems/4.11 \ <2> - 4.11/rtems-sparc <3> - Source Builder - Set Builder, v0.2.0 - Build Set: 4.11/rtems-sparc - config: expat-2.1.0-1.cfg <4> - 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 <5> - 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 <6> - 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 <7> - 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 <8> - 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 - cleaning: expat-2.1.0-x86_64-freebsd9.1-1 <9> - 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:13:43.616383 <10> - -.. topic:: Items - - 1. Providing a log file redirects the build output into a file. Logging the - build output provides a simple way to report problems. - - 2. The prefix is the location on your file system the tools are installed - into. Provide a prefix to a location you have read and write access. You - can use the prefix to install different versions or builds of tools. Just - use the path to the tools you want to use when building RTEMS. - - 3. The build set. This is the SPARC build set. First a specifically - referenced file is checked for and if not found the ``%{_configdir}`` path - is searched. The set builder will first look for files with a ``.bset`` - extension and then for a configuration file with a ``.cfg`` extension. - - 4. The SPARC build set first builds the expat library as it is used in GDB. - This is the expat configuration used. - - 5. The binutils build configuration. - - 6. The GCC and Newlib build configuration. - - 7. The GDB build configuration. - - 8. Installing the built packages to the install prefix. - - 9. All the packages built are cleaned at the end. If the build fails all the - needed files are present. You may have to clean up by deleting the build - directory if the build fails. - - 10. The time to build the package. This lets you see how different host - hardware or configurations perform. - -Your SPARC RTEMS 4.11 tool set will be installed and ready to build RTEMS and -RTEMS applications. When the build runs you will notice the tool fetch the -source code from the internet. These files are cached in directies called -``source`` and ``patches``. If you run the build again the cached files are -used. This is what happened in the shown example. Archiving these directories -archives the source you need to recreate the build. - -.. topic:: RTEMS Releases - - The RSB found in a release will automatically build and install RTEMS. If you - do not want a released version of the RSB to build RTEMS add - ``--without-rtems`` to the command line. The development version requires - adding ``--with-rtems`` to build RTEMS. Use this option to create a single - command to build the tools and RTEMS. - - The source used in release builds is downloaded from the RTEMS FTP - server. This ensures the source is always available for a release. - -The installed tools:: - - $ ls $HOME/development/rtems/4.11 - bin include lib libexec share sparc-rtems4.11 - $ ls $HOME/development/rtems/4.11/bin - sparc-rtems4.11-addr2line sparc-rtems4.11-cpp - sparc-rtems4.11-gcc-ar sparc-rtems4.11-gprof - sparc-rtems4.11-objdump sparc-rtems4.11-size - sparc-rtems4.11-ar sparc-rtems4.11-elfedit - sparc-rtems4.11-gcc-nm sparc-rtems4.11-ld - sparc-rtems4.11-ranlib sparc-rtems4.11-strings - sparc-rtems4.11-as sparc-rtems4.11-g++ - sparc-rtems4.11-gcc-ranlib sparc-rtems4.11-ld.bfd - sparc-rtems4.11-readelf sparc-rtems4.11-strip - sparc-rtems4.11-c++ sparc-rtems4.11-gcc - sparc-rtems4.11-gcov sparc-rtems4.11-nm - sparc-rtems4.11-run xmlwf - sparc-rtems4.11-c++filt sparc-rtems4.11-gcc-4.7.2 - sparc-rtems4.11-gdb sparc-rtems4.11-objcopy - sparc-rtems4.11-sis - $ $HOME/development/rtems/4.11/bin/sparc-rtems4.11-gcc -v - Using built-in specs. - COLLECT_GCC=/home/chris/development/rtems/4.11/bin/sparc-rtems4.11-gcc - COLLECT_LTO_WRAPPER=/usr/home/chris/development/rtems/4.11/bin/../ \ - libexec/gcc/sparc-rtems4.11/4.7.2/lto-wrapper - Target: sparc-rtems4.11 <1> - Configured with: ../gcc-4.7.2/configure <2> - --prefix=/home/chris/development/rtems/4.11 - --bindir=/home/chris/development/rtems/4.11/bin - --exec_prefix=/home/chris/development/rtems/4.11 - --includedir=/home/chris/development/rtems/4.11/include - --libdir=/home/chris/development/rtems/4.11/lib - --libexecdir=/home/chris/development/rtems/4.11/libexec - --mandir=/home/chris/development/rtems/4.11/share/man - --infodir=/home/chris/development/rtems/4.11/share/info - --datadir=/home/chris/development/rtems/4.11/share - --build=x86_64-freebsd9.1 --host=x86_64-freebsd9.1 --target=sparc-rtems4.11 - --disable-libstdcxx-pch --with-gnu-as --with-gnu-ld --verbose --with-newlib - --with-system-zlib --disable-nls --without-included-gettext - --disable-win32-registry --enable-version-specific-runtime-libs --disable-lto - --enable-threads --enable-plugin --enable-newlib-io-c99-formats - --enable-newlib-iconv --enable-languages=c,c++ - Thread model: rtems <3> - gcc version 4.7.2 20120920 <4> - (RTEMS 4.11 RSB cb12e4875c203f794a5cd4b3de36101ff9a88403)-1 newlib 2.0.0) (GCC) - -.. topic:: Items - - 1. The target the compiler is built for. - - 2. The configure options used to build GCC. - - 3. The threading model is always RTEMS. This makes using the RTEMS tools for - bare metal development more difficult. - - 4. The version string. It contains the Git hash of the RTEMS Source Builder - you are using. If your local clone has been modifed that state is also - recorded in the version string. The hash allows you to track from a GCC - executable back to the original source used to build it. - -.. note:: - - The RTEMS thread model enables specific hooks in GCC so applications built - with RTEMS tools need the RTEMS runtime to operate correctly. You can use - RTEMS tools to build bare metal component but it is more difficult than with - a bare metal tool chain and you need to know what you are doing at a low - level. The RTEMS Source Builder can build bare metal tool chains as - well. Look in the top level ``bare`` directory. - -Deployment ----------- - -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. - -Controlling the Build ---------------------- - -Build sets can be controlled via the command line to enable and disable various -features. There is no definitive list of build options that can be listed -because they are implemented with the configuration scripts. The best way to -find what is available is to grep the configuration files. for ``with`` and -``without``. - -Following are currently available: - -``--without-rtems`` - Do not build RTEMS when building an RTEMS build set. - -``--without-cxx`` - Do not build a C++ compiler. - -``--with-ada`` - Attempt to build an Ada compiler. You need a native GNAT installed. - -``--with-fortran`` - Attempt to build a Fortran compiler. - -``--with-objc`` - Attempt to build a C++ compiler. diff --git a/rsb/source-builder.rst b/rsb/source-builder.rst index ef5ba61..7e81244 100644 --- a/rsb/source-builder.rst +++ b/rsb/source-builder.rst @@ -66,10 +66,11 @@ a problem please ask on our :r:list:`devel`. .. comment: TBD: The section "Installing and Tar Files" does not exist. This documentation caters for a range of users from new to experienced RTEMS -developers. New users can follow the Quick Start section up to the "Installing -and Tar Files" to get a working tools and RTEMS. Users building a binary tool -set for release can read the "Installing and Tar Files". Users wanting to run -and test bleeding edge tools or packages, or wanting update or extend the RSB's +developers who want to understand the RTEMS Source Builder. New users +who just want to build tools should follow the Quick Start section in +the User's Guide. Users building a binary tool set for release can +read the "Installing and Tar Files". Users wanting to run and test +bleeding edge tools or packages, or wanting update or extend the RSB's configuration can read the remaining sections. .. topic:: Bug Reporting @@ -154,3 +155,31 @@ The *SpecBuilder* tool did not build tools or packages unrelated to the RTEMS Project where no suitable *spec* file was available so another tool was needed. Rather than start again Chris decided to take the parsing code for the *spec* file format and build a new tool called the RTEMS Source Builder. + +Controlling the Tools Build +--------------------------- + +Build sets can be controlled via the command line to enable and disable various +features. There is no definitive list of build options that can be listed +because they are implemented with the configuration scripts. The best way to +find what is available is to grep the configuration files. for ``with`` and +``without``. + +Following are currently available: + +``--without-rtems`` + Do not build RTEMS when building an RTEMS build set. + +``--without-cxx`` + Do not build a C++ compiler. + +``--with-ada`` + Attempt to build an Ada compiler. You need a native GNAT installed. + +``--with-fortran`` + Attempt to build a Fortran compiler. + +``--with-objc`` + Attempt to build a C++ compiler. + + 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