.. 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.