diff options
Diffstat (limited to 'user/installation')
| -rw-r--r-- | user/installation/developer.rst | 672 | ||||
| -rw-r--r-- | user/installation/index.rst | 47 | ||||
| -rw-r--r-- | user/installation/prefixes-sandboxing.rst | 151 | ||||
| -rw-r--r-- | user/installation/releases.rst | 284 |
4 files changed, 1154 insertions, 0 deletions
diff --git a/user/installation/developer.rst b/user/installation/developer.rst new file mode 100644 index 0000000..0db4a51 --- /dev/null +++ b/user/installation/developer.rst @@ -0,0 +1,672 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. comment: Copyright (c) 2016 Chris Johns <chrisj@rtems.org> +.. comment: All rights reserved. + +.. _developer: +.. _development-version: +.. _unstable: + +Developer (Unstable) +-------------------- +.. index:: Git + +RTEMS provides open access to it's development processes. We call this the +developer set up. The project encouages all users to inspect, review, comment +and contribute to the code base. The processes described here are the same +processes the core development team use when developing and maintaining RTEMS. + +.. warning:: + + The development version is not for use in production and it can break from + time to time. + +Please read :ref:`development-host` before continuing. The following procedure +assumes you have installed and configured your host operating system. It also +assumes you have installed any dependent packages needed when building the +tools and the kernel. + +You need to select a location to build and install the RTEMS Tool chain and +RTEMS. Make sure there is plenty of disk space and a fast disk is +recommended. Our procedure will document building and installing the tools in a +home directory called :file:`development/rtems`. Using a home directory means +you can do this without needing to be root. You can also use +:file:`/opt/rtems/build` if you have access to that path. + +The location used to install the tools and kernel is called the `prefix`. It is +best to have a `prefix` for each different version of RTEMS you are using. If +you are using RTEMS 4.11 in production it is not a good idea to install a +development version of 4.12 over the top. A separate `prefix` for each version +avoids this. + +The RTEMS tool chain changes less often than the RTEMS kernel. One method of +working with development releases is to have a separate `prefix` for the RTEMS +tools and a different one for the RTEMS kernel. You can then update each +without interacting with the other. You can also have a number of RTEMS +versions available to test with. + +.. sidebar:: *Downloading the source* + + You need an internet connection to download the source. The downloaded source + is cached locally and the RSB checksums it. If you run a build again the + download output will be missing. Using the RSB from git will download the + source from the upstream project's home site and this could be `http`, `ftp`, + or `git`. + +.. _posix-host-tools-chain: +.. _macos-host-tools-chain: + +POSIX and OS X Host Tools Chain +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This procedure will build a SPARC tool chain. + +Clone the RTEMS Source Builder (RSB) repository: + +.. code-block:: shell + + $ cd + $ mkdir -p development/rtems + $ cd development/rtems + $ git clone git://git.rtems.org/rtems-source-builder.git rsb + Cloning into 'rsb'... + remote: Counting objects: 5837, done. + remote: Compressing objects: 100% (2304/2304), done. + remote: Total 5837 (delta 4014), reused 5056 (delta 3494) + Receiving objects: 100% (5837/5837), 2.48 MiB | 292.00 KiB/s, done. + Resolving deltas: 100% (4014/4014), done. + Checking connectivity... done. + +Check all the host packages you need are present. Current libraries are not +checked and this includes checking for the python development libraries GDB +requires: + +.. code-block:: shell + + $ cd rsb + $ ./source-builder/sb-check + RTEMS Source Builder - Check, 4.12 (e645642255cc) + Environment is ok + +Build a tool chain for the SPARC architecure. We are using the SPARC +architecture because GDB has a good simulator that lets us run and test the +samples RTEMS builds by default. The current development version +is `4.12` and is on master: + +.. code-block:: shell + + $ cd rtems + $ ../source-builder/sb-set-builder \ + --prefix=/usr/home/chris/development/rtems/4.12 4.12/rtems-sparc + RTEMS Source Builder - Set Builder, 4.12 (e645642255cc) + Build Set: 4.12/rtems-sparc + Build Set: 4.12/rtems-autotools.bset + Build Set: 4.12/rtems-autotools-internal.bset + config: tools/rtems-autoconf-2.69-1.cfg + package: autoconf-2.69-x86_64-linux-gnu-1 + Creating source directory: sources + download: ftp://ftp.gnu.org/gnu/autoconf/autoconf-2.69.tar.gz -> sources/autoconf-2.69.tar.gz + downloading: sources/autoconf-2.69.tar.gz - 1.8MB of 1.8MB (100%) + building: autoconf-2.69-x86_64-linux-gnu-1 + config: tools/rtems-automake-1.12.6-1.cfg + package: automake-1.12.6-x86_64-linux-gnu-1 + download: ftp://ftp.gnu.org/gnu/automake/automake-1.12.6.tar.gz -> sources/automake-1.12.6.tar.gz + downloading: sources/automake-1.12.6.tar.gz - 2.0MB of 2.0MB (100%) + Creating source directory: patches + 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 + downloading: patches/automake-1.12.6-bugzilla.redhat.com-1239379.diff - 408.0 bytes of 408.0 bytes (100%) + building: automake-1.12.6-x86_64-linux-gnu-1 + cleaning: autoconf-2.69-x86_64-linux-gnu-1 + cleaning: automake-1.12.6-x86_64-linux-gnu-1 + Build Set: Time 0:00:17.465024 + Build Set: 4.12/rtems-autotools-base.bset + config: tools/rtems-autoconf-2.69-1.cfg + package: autoconf-2.69-x86_64-linux-gnu-1 + building: autoconf-2.69-x86_64-linux-gnu-1 + reporting: tools/rtems-autoconf-2.69-1.cfg -> autoconf-2.69-x86_64-linux-gnu-1.txt + reporting: tools/rtems-autoconf-2.69-1.cfg -> autoconf-2.69-x86_64-linux-gnu-1.xml + config: tools/rtems-automake-1.12.6-1.cfg + package: automake-1.12.6-x86_64-linux-gnu-1 + building: automake-1.12.6-x86_64-linux-gnu-1 + reporting: tools/rtems-automake-1.12.6-1.cfg -> automake-1.12.6-x86_64-linux-gnu-1.txt + reporting: tools/rtems-automake-1.12.6-1.cfg -> automake-1.12.6-x86_64-linux-gnu-1.xml + installing: autoconf-2.69-x86_64-linux-gnu-1 -> /usr/home/chris/development/rtems/4.12 + installing: automake-1.12.6-x86_64-linux-gnu-1 -> /usr/home/chris/development/rtems/4.12 + cleaning: autoconf-2.69-x86_64-linux-gnu-1 + cleaning: automake-1.12.6-x86_64-linux-gnu-1 + Build Set: Time 0:00:05.358624 + Build Set: Time 0:00:22.824422 + config: devel/expat-2.1.0-1.cfg + package: expat-2.1.0-x86_64-linux-gnu-1 + download: http://downloads.sourceforge.net/project/expat/expat/2.1.0/expat-2.1.0.tar.gz -> sources/expat-2.1.0.tar.gz + redirect: http://internode.dl.sourceforge.net/project/expat/expat/2.1.0/expat-2.1.0.tar.gz + downloading: sources/expat-2.1.0.tar.gz - 549.4kB of 549.4kB (100%) + building: expat-2.1.0-x86_64-linux-gnu-1 + reporting: devel/expat-2.1.0-1.cfg -> expat-2.1.0-x86_64-linux-gnu-1.txt + reporting: devel/expat-2.1.0-1.cfg -> expat-2.1.0-x86_64-linux-gnu-1.xml + config: tools/rtems-binutils-2.26-1.cfg + package: sparc-rtems4.12-binutils-2.26-x86_64-linux-gnu-1 + download: ftp://ftp.gnu.org/gnu/binutils/binutils-2.26.tar.bz2 -> sources/binutils-2.26.tar.bz2 + downloading: sources/binutils-2.26.tar.bz2 - 24.4MB of 24.4MB (100%) + 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 + downloading: patches/binutils-2.26-rtems-aarch64-x86_64.patch - 3.2kB of 3.2kB (100%) + building: sparc-rtems4.12-binutils-2.26-x86_64-linux-gnu-1 + reporting: tools/rtems-binutils-2.26-1.cfg -> sparc-rtems4.12-binutils-2.26-x86_64-linux-gnu-1.txt + reporting: tools/rtems-binutils-2.26-1.cfg -> sparc-rtems4.12-binutils-2.26-x86_64-linux-gnu-1.xml + config: tools/rtems-gcc-6-20160228-newlib-2.3.0.20160226-1.cfg + package: sparc-rtems4.12-gcc-6-20160228-newlib-2.3.0.20160226-x86_64-linux-gnu-1 + download: ftp://gcc.gnu.org/pub/gcc/snapshots/6-20160228/gcc-6-20160228.tar.bz2 -> sources/gcc-6-20160228.tar.bz2 + downloading: sources/gcc-6-20160228.tar.bz2 - 90.8MB of 90.8MB (100%) + download: ftp://sourceware.org/pub/newlib/newlib-2.3.0.20160226.tar.gz -> sources/newlib-2.3.0.20160226.tar.gz + downloading: sources/newlib-2.3.0.20160226.tar.gz - 16.9MB of 16.9MB (100%) + download: http://www.mpfr.org/mpfr-2.4.2/mpfr-2.4.2.tar.bz2 -> + sources/mpfr-2.4.2.tar.bz2 + downloading: sources/mpfr-2.4.2.tar.bz2 - 1.0MB of 1.0MB (100%) + download: http://www.multiprecision.org/mpc/download/mpc-0.8.1.tar.gz -> sources/mpc-0.8.1.tar.gz + downloading: sources/mpc-0.8.1.tar.gz - 532.2kB of 532.2kB (100%) + download: ftp://ftp.gnu.org/gnu/gmp/gmp-4.3.2.tar.bz2 -> sources/gmp-4.3.2.tar.bz2 + downloading: sources/gmp-4.3.2.tar.bz2 - 1.8MB of 1.8MB (100%) + building: sparc-rtems4.12-gcc-6-20160228-newlib-2.3.0.20160226-x86_64-linux-gnu-1 + 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 + 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 + config: tools/rtems-gdb-7.9-1.cfg + package: sparc-rtems4.12-gdb-7.9-x86_64-linux-gnu-1 + download: http://ftp.gnu.org/gnu/gdb/gdb-7.9.tar.xz -> sources/gdb-7.9.tar.xz + downloading: sources/gdb-7.9.tar.xz - 17.0MB of 17.0MB (100%) + download: https://git.rtems.org/rtems-tools/plain/tools/4.12/gdb/gdb-sim-arange-inline.diff -> patches/gdb-sim-arange-inline.diff + downloading: patches/gdb-sim-arange-inline.diff - 761.0 bytes of 761.0 bytes (100%) + download: https://git.rtems.org/rtems-tools/plain/tools/4.12/gdb/gdb-sim-cgen-inline.diff -> patches/gdb-sim-cgen-inline.diff + downloading: patches/gdb-sim-cgen-inline.diff - 706.0 bytes of 706.0 bytes (100%) + 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 + downloading: patches/gdb-7.9-aarch64-x86_64.patch - 1.7kB of 1.7kB (100%) + building: sparc-rtems4.12-gdb-7.9-x86_64-linux-gnu-1 + reporting: tools/rtems-gdb-7.9-1.cfg -> sparc-rtems4.12-gdb-7.9-x86_64-linux-gnu-1.txt + reporting: tools/rtems-gdb-7.9-1.cfg -> sparc-rtems4.12-gdb-7.9-x86_64-linux-gnu-1.xml + config: tools/rtems-tools-4.12-1.cfg + package: rtems-tools-HEAD-1 + Creating source directory: sources/git + git: clone: git://git.rtems.org/rtems-tools.git -> sources/git/rtems-tools.git + git: reset: git://git.rtems.org/rtems-tools.git + git: fetch: git://git.rtems.org/rtems-tools.git -> sources/git/rtems-tools.git + git: checkout: git://git.rtems.org/rtems-tools.git => HEAD + git: pull: git://git.rtems.org/rtems-tools.git + building: rtems-tools-HEAD-1 + reporting: tools/rtems-tools-4.12-1.cfg -> rtems-tools-HEAD-1.txt + reporting: tools/rtems-tools-4.12-1.cfg -> rtems-tools-HEAD-1.xml + installing: expat-2.1.0-x86_64-linux-gnu-1 -> /usr/home/chris/development/rtems/4.12 + installing: sparc-rtems4.12-binutils-2.26-x86_64-linux-gnu-1 -> /usr/home/chris/development/rtems/4.12 + installing: sparc-rtems4.12-gcc-6-20160228-newlib-2.3.0.20160226-x86_64-linux-gnu-1 -> /usr/home/chris/development/rtems/4.12 + installing: sparc-rtems4.12-gdb-7.9-x86_64-linux-gnu-1 -> /usr/home/chris/development/rtems/4.12 + installing: rtems-tools-HEAD-1 -> /usr/home/chris/development/rtems/4.12 + cleaning: expat-2.1.0-x86_64-linux-gnu-1 + cleaning: sparc-rtems4.12-binutils-2.26-x86_64-linux-gnu-1 + cleaning: sparc-rtems4.12-gcc-6-20160228-newlib-2.3.0.20160226-x86_64-linux-gnu-1 + cleaning: sparc-rtems4.12-gdb-7.9-x86_64-linux-gnu-1 + cleaning: rtems-tools-HEAD-1 + Build Set: Time 0:31:09.754219 + +.. _windows-tool-chain: + +Windows Host Tool Chain +~~~~~~~~~~~~~~~~~~~~~~~ +.. index:: Microsoft Windows Installation + +This section details how you create an RTEMS development environment on +Windows. The installation documented here is on `Windows 7 64bit +Professional`. Building on `Windows 10` has been reported as working. + +Please see :ref:`microsoft-windows` before continuing. + +.. note:: + + If the RSB reports ``error: no hosts defaults found; please add`` you have + probably opened an MSYS2 32bit Shell. Close all 32bit Shell windows and open + the MSYS2 64bit Shell. + +RTEMS Windows Tools +^^^^^^^^^^^^^^^^^^^ + +Create a workspace for RTEMS using the following shell command: + +.. sidebar:: *Creating Tool Archives* + + Add ``--bset-tar-file`` to the ``sb-set-builder`` command line to create + tar files of the built package set. + +.. code-block:: shell + + ~ + $ mkdir -p /c/opt/rtems + +The ``/c`` path is an internal MSYS2 mount point of the ``C:`` drive. The +command creates the RTEMS work space on the ``C:`` drive. If you wish to use +another drive please subsitute ``/c`` with your drive letter. + +We build and install all RTEMS packages under the `prefix` we just +created. Change to that directory and get a copy of the RSB: + +.. code-block:: shell + + ~ + $ cd /c/opt/rtems + /c/opt/rtems + $ git clone git://git.rtems.org/rtems-source-builder.git rsb + Cloning into 'rsb'... + remote: Counting objects: 5716, done. + remote: Compressing objects: 100% (2183/2183), done. + remote: Total 5716 (delta 3919), reused 5071 (delta 3494) + Receiving objects: 100% (5716/5716), 2.46 MiB | 656.00 KiB/s, done. + Resolving deltas: 100% (3919/3919), done. + Checking connectivity... done. + Checking out files: 100% (630/630), done. + /c/opt/rtems + $ cd rsb + +We are building RTEMS 4.11 tools so select the *4.11* branch: + +.. code-block:: shell + + /c/opt/rtems/rsb + $ git checkout 4.11 + Branch 4.11 set up to track remote branch 4.11 from origin. + Switched to a new branch '4.11' + /c/opt/rtems/rsb + $ + +Check the RSB has a valid environment: + +.. code-block:: shell + + /c/opt/rtems/rsb + $ cd rtems + /c/opt/rtems/rsb/rtems + $ ../source-builder/sb-check + RTEMS Source Builder - Check, 4.11 (01ac76f2f90f) + Environment is ok + /c/opt/rtems/rsb/rtems + $ + +To build a set of RTEMS tools for the Intel ``i386`` architecture. The build +runs a single job rather than a job per CPU in your machine and will take a +long time so please be patient. The RSB creates a log file containing all the +build output and it will be changing size. The RSB command to build ``i386`` +tools is: + +.. code-block:: shell + + /c/opt/rtems/rsb/rtems + $ ../source-builder/sb-set-builder --prefix=/c/opt/rtems/4.11 \ + --jobs=none 4.11/rtems-i386 + RTEMS Source Builder - Set Builder, 4.11 (01ac76f2f90f) + Build Set: 4.11/rtems-i386 + Build Set: 4.11/rtems-autotools.bset + Build Set: 4.11/rtems-autotools-internal.bset + config: tools/rtems-autoconf-2.69-1.cfg + package: autoconf-2.69-x86_64-w64-mingw32-1 + Creating source directory: sources + download: ftp://ftp.gnu.org/gnu/autoconf/autoconf-2.69.tar.gz -> sources/autoconf-2.69.tar.gz + downloading: sources/autoconf-2.69.tar.gz - 1.8MB of 1.8MB (100%) + building: autoconf-2.69-x86_64-w64-mingw32-1 + config: tools/rtems-automake-1.12.6-1.cfg + package: automake-1.12.6-x86_64-w64-mingw32-1 + download: ftp://ftp.gnu.org/gnu/automake/automake-1.12.6.tar.gz -> sources/automake-1.12.6.tar.gz + downloading: sources/automake-1.12.6.tar.gz - 2.0MB of 2.0MB (100%) + building: automake-1.12.6-x86_64-w64-mingw32-1 + cleaning: autoconf-2.69-x86_64-w64-mingw32-1 + cleaning: automake-1.12.6-x86_64-w64-mingw32-1 + Build Set: Time 0:00:42.515625 + Build Set: 4.11/rtems-autotools-base.bset + config: tools/rtems-autoconf-2.69-1.cfg + package: autoconf-2.69-x86_64-w64-mingw32-1 + building: autoconf-2.69-x86_64-w64-mingw32-1 + reporting: tools/rtems-autoconf-2.69-1.cfg -> autoconf-2.69-x86_64-w64-mingw32-1.txt + reporting: tools/rtems-autoconf-2.69-1.cfg -> autoconf-2.69-x86_64-w64-mingw32-1.xml + config: tools/rtems-automake-1.12.6-1.cfg + package: automake-1.12.6-x86_64-w64-mingw32-1 + building: automake-1.12.6-x86_64-w64-mingw32-1 + reporting: tools/rtems-automake-1.12.6-1.cfg -> automake-1.12.6-x86_64-w64-mingw32-1.txt + reporting: tools/rtems-automake-1.12.6-1.cfg -> automake-1.12.6-x86_64-w64-mingw32-1.xml + tarball: tar/rtems-4.11-autotools-x86_64-w64-mingw32-1.tar.bz2 + installing: autoconf-2.69-x86_64-w64-mingw32-1 -> C:\opt\rtems\4.11 + installing: automake-1.12.6-x86_64-w64-mingw32-1 -> C:\opt\rtems\4.11 + cleaning: autoconf-2.69-x86_64-w64-mingw32-1 + cleaning: automake-1.12.6-x86_64-w64-mingw32-1 + Build Set: Time 0:00:37.718750 + Build Set: Time 0:01:20.234375 + config: devel/expat-2.1.0-1.cfg + package: expat-2.1.0-x86_64-w64-mingw32-1 + download: http://downloads.sourceforge.net/project/expat/expat/2.1.0/expat-2.1.0.tar.gz -> sources/expat-2.1.0.tar.gz + redirect: http://iweb.dl.sourceforge.net/project/expat/expat/2.1.0/expat-2.1.0.tar.gz + downloading: sources/expat-2.1.0.tar.gz - 549.4kB of 549.4kB (100%) + building: expat-2.1.0-x86_64-w64-mingw32-1 + reporting: devel/expat-2.1.0-1.cfg -> expat-2.1.0-x86_64-w64-mingw32-1.txt + reporting: devel/expat-2.1.0-1.cfg -> expat-2.1.0-x86_64-w64-mingw32-1.xml + config: tools/rtems-binutils-2.24-1.cfg + package: i386-rtems4.11-binutils-2.24-x86_64-w64-mingw32-1 + download: ftp://ftp.gnu.org/gnu/binutils/binutils-2.24.tar.bz2 -> sources/binutils-2.24.tar.bz2 + downloading: sources/binutils-2.24.tar.bz2 - 21.7MB of 21.7MB (100%) + building: i386-rtems4.11-binutils-2.24-x86_64-w64-mingw32-1 + reporting: tools/rtems-binutils-2.24-1.cfg -> i386-rtems4.11-binutils-2.24-x86_64-w64-mingw32-1.txt + reporting: tools/rtems-binutils-2.24-1.cfg -> i386-rtems4.11-binutils-2.24-x86_64-w64-mingw32-1.xml + config: tools/rtems-gcc-4.9.3-newlib-2.2.0-20150423-1.cfg + package: i386-rtems4.11-gcc-4.9.3-newlib-2.2.0.20150423-x86_64-w64-mingw32-1 + download: ftp://ftp.gnu.org/gnu/gcc/gcc-4.9.3/gcc-4.9.3.tar.bz2 -> sources/gcc-4.9.3.tar.bz2 + downloading: sources/gcc-4.9.3.tar.bz2 - 85.8MB of 85.8MB (100%) + download: ftp://sourceware.org/pub/newlib/newlib-2.2.0.20150423.tar.gz -> sources/newlib-2.2.0.20150423.tar.gz + downloading: sources/newlib-2.2.0.20150423.tar.gz - 16.7MB of 16.7MB (100%) + download: http://www.mpfr.org/mpfr-3.0.1/mpfr-3.0.1.tar.bz2 -> sources/mpfr-3.0.1.tar.bz2 + downloading: sources/mpfr-3.0.1.tar.bz2 - 1.1MB of 1.1MB (100%) + download: http://www.multiprecision.org/mpc/download/mpc-0.8.2.tar.gz -> sources/mpc-0.8.2.tar.gz + downloading: sources/mpc-0.8.2.tar.gz - 535.5kB of 535.5kB (100%) + download: ftp://ftp.gnu.org/gnu/gmp/gmp-5.0.5.tar.bz2 -> sources/gmp-5.0.5.tar.bz2 + downloading: sources/gmp-5.0.5.tar.bz2 - 2.0MB of 2.0MB (100%) + building: i386-rtems4.11-gcc-4.9.3-newlib-2.2.0.20150423-x86_64-w64-mingw32-1 + reporting: tools/rtems-gcc-4.9.3-newlib-2.2.0-20150423-1.cfg -> + i386-rtems4.11-gcc-4.9.3-newlib-2.2.0.20150423-x86_64-w64-mingw32-1.txt + reporting: tools/rtems-gcc-4.9.3-newlib-2.2.0-20150423-1.cfg -> + i386-rtems4.11-gcc-4.9.3-newlib-2.2.0.20150423-x86_64-w64-mingw32-1.xml + config: tools/rtems-gdb-7.9-1.cfg + package: i386-rtems4.11-gdb-7.9-x86_64-w64-mingw32-1 + download: http://ftp.gnu.org/gnu/gdb/gdb-7.9.tar.xz -> sources/gdb-7.9.tar.xz + downloading: sources/gdb-7.9.tar.xz - 17.0MB of 17.0MB (100%) + download: https://git.rtems.org/rtems-tools/plain/tools/4.11/gdb/gdb-sim-arange-inline.diff -> patches/gdb-sim-arange-inline.diff + downloading: patches/gdb-sim-arange-inline.diff - 761.0 bytes of 761.0 bytes (100%) + download: https://git.rtems.org/rtems-tools/plain/tools/4.11/gdb/gdb-sim-cgen-inline.diff -> patches/gdb-sim-cgen-inline.diff + downloading: patches/gdb-sim-cgen-inline.diff - 706.0 bytes of 706.0 bytes (100%) + building: i386-rtems4.11-gdb-7.9-x86_64-w64-mingw32-1 + reporting: tools/rtems-gdb-7.9-1.cfg -> + i386-rtems4.11-gdb-7.9-x86_64-w64-mingw32-1.txt + reporting: tools/rtems-gdb-7.9-1.cfg -> + i386-rtems4.11-gdb-7.9-x86_64-w64-mingw32-1.xml + config: tools/rtems-tools-4.11-1.cfg + package: rtems-tools-4.11-1 + Creating source directory: sources/git + git: clone: git://git.rtems.org/rtems-tools.git -> sources/git/rtems-tools.git + git: reset: git://git.rtems.org/rtems-tools.git + git: fetch: git://git.rtems.org/rtems-tools.git -> sources/git/rtems-tools.git + git: checkout: git://git.rtems.org/rtems-tools.git => 4.11 + git: pull: git://git.rtems.org/rtems-tools.git + building: rtems-tools-4.11-1 + reporting: tools/rtems-tools-4.11-1.cfg -> rtems-tools-4.11-1.txt + reporting: tools/rtems-tools-4.11-1.cfg -> rtems-tools-4.11-1.xml + config: tools/rtems-kernel-4.11.cfg + installing: expat-2.1.0-x86_64-w64-mingw32-1 -> C:\opt\rtems\4.11 + installing: i386-rtems4.11-binutils-2.24-x86_64-w64-mingw32-1 -> C:\opt\rtems\4.11 + installing: i386-rtems4.11-gcc-4.9.3-newlib-2.2.0.20150423-x86_64-w64-mingw32-1 -> C:\opt\rtems\4.11 + installing: i386-rtems4.11-gdb-7.9-x86_64-w64-mingw32-1 -> C:\opt\rtems\4.11 + installing: rtems-tools-4.11-1 -> C:\opt\rtems\4.11 + cleaning: expat-2.1.0-x86_64-w64-mingw32-1 + cleaning: i386-rtems4.11-binutils-2.24-x86_64-w64-mingw32-1 + cleaning: i386-rtems4.11-gcc-4.9.3-newlib-2.2.0.20150423-x86_64-w64-mingw32-1 + cleaning: i386-rtems4.11-gdb-7.9-x86_64-w64-mingw32-1 + cleaning: rtems-tools-4.11-1 + Build Set: Time 1:32:58.972919 + /c/opt/rtems/rsb/rtems + $ + +.. _rtems-kernel-install: + +Building the Kernel +^^^^^^^^^^^^^^^^^^^ + +We can now build the RTEMS kernel using the RTEMS tools we have just +built. First we need to set the path to the tools: + +.. code-block:: shell + + /c + $ cd /c/opt/rtems + /c/opt/rtems + $ export PATH=/c/opt/rtems/4.11/bin:$PATH + /c/opt/rtems + $ + +We currently build RTEMS from the git release branch for 4.11: + +.. code-block:: shell + + /c/opt/rtems + $ mkdir kernel + /c/opt/rtems + $ cd kernel + /c/opt/rtems/kernel + $ git clone git://git.rtems.org/rtems.git rtems + Cloning into 'rtems'... + remote: Counting objects: 482766, done. + remote: Compressing objects: 100% (88781/88781), done. + remote: Total 482766 (delta 389610), reused 475155 (delta 383437) + Receiving objects: 100% (482766/482766), 69.77 MiB | 697.00 KiB/s, done. + Resolving deltas: 100% (389610/389610), done. + Checking connectivity... done. + Checking out files: 100% (10626/10626), done. + /c/opt/rtems/kernel + $ cd rtems + /c/opt/rtems/kernel/rtems + $ git checkout 4.11 + Checking out files: 100% (2553/2553), done. + Branch 4.11 set up to track remote branch 4.11 from origin. + Switched to a new branch '4.11' + /c/opt/rtems/kernel + $ + +The kernel code cloned from git needs to be `bootstrapped`. Bootstrapping +creates ``autoconf`` and ``automake`` generated files. To bootstrap we first +clean away any files, then generate the pre-install header file lists and +finally we generate the ``autoconf`` and ``automake`` files using the RSB's +bootstrap tool. First we clean any generated files that exist: + +.. code-block:: shell + + /c/opt/rtems/kernel/rtems + $ ./bootstrap -c + removing automake generated Makefile.in files + removing configure files + removing aclocal.m4 files + +Then we generate the pre-install header file automake make files: + +.. code-block:: shell + + /c/opt/rtems/kernel/rtems + $ ./bootstrap -p + Generating ./c/src/ada/preinstall.am + Generating ./c/src/lib/libbsp/arm/altera-cyclone-v/preinstall.am + Generating ./c/src/lib/libbsp/arm/atsam/preinstall.am + Generating ./c/src/lib/libbsp/arm/beagle/preinstall.am + Generating ./c/src/lib/libbsp/arm/csb336/preinstall.am + Generating ./c/src/lib/libbsp/arm/csb337/preinstall.am + Generating ./c/src/lib/libbsp/arm/edb7312/preinstall.am + Generating ./c/src/lib/libbsp/arm/gdbarmsim/preinstall.am + ....... + Generating ./cpukit/score/cpu/mips/preinstall.am + Generating ./cpukit/score/cpu/moxie/preinstall.am + Generating ./cpukit/score/cpu/nios2/preinstall.am + Generating ./cpukit/score/cpu/no_cpu/preinstall.am + Generating ./cpukit/score/cpu/or1k/preinstall.am + Generating ./cpukit/score/cpu/powerpc/preinstall.am + Generating ./cpukit/score/cpu/sh/preinstall.am + Generating ./cpukit/score/cpu/sparc/preinstall.am + Generating ./cpukit/score/cpu/sparc64/preinstall.am + Generating ./cpukit/score/cpu/v850/preinstall.am + Generating ./cpukit/score/preinstall.am + Generating ./cpukit/telnetd/preinstall.am + Generating ./cpukit/wrapup/preinstall.am + Generating ./cpukit/zlib/preinstall.am + /c/opt/rtems/kernel/rtems + +Finally we run the RSB's parallel ``bootstrap`` command: + +.. code-block:: shell + + $ /c/opt/rtems/rsb/source-builder/sb-bootstrap + RTEMS Source Builder - RTEMS Bootstrap, 4.11 (76188ee494dd) + 1/139: autoreconf: configure.ac + 2/139: autoreconf: c/configure.ac + 3/139: autoreconf: c/src/configure.ac + 4/139: autoreconf: c/src/ada-tests/configure.ac + 5/139: autoreconf: c/src/lib/libbsp/arm/configure.ac + 6/139: autoreconf: c/src/lib/libbsp/arm/altera-cyclone-v/configure.ac + 7/139: autoreconf: c/src/lib/libbsp/arm/atsam/configure.ac + 8/139: autoreconf: c/src/lib/libbsp/arm/beagle/configure.ac + 9/139: autoreconf: c/src/lib/libbsp/arm/csb336/configure.ac + 10/139: autoreconf: c/src/lib/libbsp/arm/csb337/configure.ac + 11/139: autoreconf: c/src/lib/libbsp/arm/edb7312/configure.ac + ....... + 129/139: autoreconf: testsuites/samples/configure.ac + 130/139: autoreconf: testsuites/smptests/configure.ac + 131/139: autoreconf: testsuites/sptests/configure.ac + 132/139: autoreconf: testsuites/tmtests/configure.ac + 133/139: autoreconf: testsuites/tools/configure.ac + 134/139: autoreconf: testsuites/tools/generic/configure.ac + 135/139: autoreconf: tools/build/configure.ac + 136/139: autoreconf: tools/cpu/configure.ac + 137/139: autoreconf: tools/cpu/generic/configure.ac + 138/139: autoreconf: tools/cpu/nios2/configure.ac + 139/139: autoreconf: tools/cpu/sh/configure.ac + Bootstrap time: 0:20:38.759766 + /c/opt/rtems/kernel/rtems + $ + +We will build the RTEMS kernel for the ``i386`` target and the ``pc686`` +BSP. You can check the available BSPs by running the ``rtems-bsps`` command +found in the top directory of the RTEMS kernel source. We build the Board +Support Package (BSP) outside the kernel source tree: + +.. code-block:: shell + + /c/opt/rtems/kernel/rtems + $ cd .. + /c/opt/rtems/kernel + $ mkdir pc686 + /c/opt/rtems/kernel + $ cd pc686 + /c/opt/rtems/kernel/pc686 + $ + +Configure the RTEMS kernel to build ``pc686`` BSP for the ``i386`` target with +networking disabled, We will build the external libBSD stack later: + +.. code-block:: shell + + /c/opt/rtems/kernel/pc686 + $ /c/opt/rtems/kernel/rtems/configure --prefix=/c/opt/rtems/4.11 \ + --target=i386-rtems4.11 --disable-networking --enable-rtemsbsp=pc686 + checking for gmake... no + checking for make... make + checking for RTEMS Version... 4.11.99.0 + checking build system type... x86_64-pc-mingw64 + checking host system type... x86_64-pc-mingw64 + checking target system type... i386-pc-rtems4.11 + checking for a BSD-compatible install... /usr/bin/install -c + checking whether build environment is sane... yes + checking for a thread-safe mkdir -p... /usr/bin/mkdir -p + checking for gawk... gawk + checking whether make sets $(MAKE)... yes + checking whether to enable maintainer-specific portions of Makefiles... no + checking that generated files are newer than configure... done + configure: creating ./config.status + configure: configuring in ./tools/build + ....... + checking whether make sets $(MAKE)... yes + checking whether to enable maintainer-specific portions of Makefiles... no + checking that generated files are newer than configure... done + configure: creating ./config.status + config.status: creating Makefile + + target architecture: i386. + available BSPs: pc686. + 'make all' will build the following BSPs: pc686. + other BSPs can be built with 'make RTEMS_BSP="bsp1 bsp2 ..."' + + config.status: creating Makefile + /c/opt/rtems/kernel/pc686 + $ + +Build the kernel: + +.. code-block:: shell + + /c/opt/rtems/kernel/pc686 + $ make + Making all in tools/build + make[1]: Entering directory '/c/opt/rtems/kernel/pc686/tools/build' + make all-am + make[2]: Entering directory '/c/opt/rtems/kernel/pc686/tools/build' + gcc -DHAVE_CONFIG_H -I. -I/c/opt/rtems/kernel/rtems/tools/build -g -O2 -MT + cklength.o -MD -MP -MF .deps/cklength.Tpo -c -o cklength.o + /c/opt/rtems/kernel/rtems/tools/build/cklength.c + gcc -DHAVE_CONFIG_H -I. -I/c/opt/rtems/kernel/rtems/tools/build -g -O2 -MT + eolstrip.o -MD -MP -MF .deps/eolstrip.Tpo -c -o eolstrip.o + /c/opt/rtems/kernel/rtems/tools/build/eolstrip.c + .......... + i386-rtems4.11-objcopy -O binary nsecs.nxe nsecs.bin + ../../../../../pc686/build-tools/bin2boot -v nsecs.ralf 0x00097E00 + ../../../../../pc686/lib/start16.bin 0x00097C00 0 nsecs.bin 0x00100000 0 + header address 0x00097e00, its memory size 0xzx + first image address 0x00097c00, its memory size 0x00000200 + second image address 0x00100000, its memory size 0x0003d800 + rm -f nsecs.nxe + make[6]: Leaving directory '/c/opt/rtems/kernel/pc686/i386-rtems4.11/c/pc686/testsuites/samples/nsecs' + make[5]: Leaving directory '/c/opt/rtems/kernel/pc686/i386-rtems4.11/c/pc686/testsuites/samples' + make[4]: Leaving directory '/c/opt/rtems/kernel/pc686/i386-rtems4.11/c/pc686/testsuites/samples' + make[4]: Entering directory '/c/opt/rtems/kernel/pc686/i386-rtems4.11/c/pc686/testsuites' + make[4]: Nothing to be done for 'all-am'. + make[4]: Leaving directory '/c/opt/rtems/kernel/pc686/i386-rtems4.11/c/pc686/testsuites' + make[3]: Leaving directory '/c/opt/rtems/kernel/pc686/i386-rtems4.11/c/pc686/testsuites' + make[2]: Leaving directory '/c/opt/rtems/kernel/pc686/i386-rtems4.11/c/pc686' + make[1]: Leaving directory '/c/opt/rtems/kernel/pc686/i386-rtems4.11/c' + make[1]: Entering directory '/c/opt/rtems/kernel/pc686' + make[1]: Nothing to be done for 'all-am'. + make[1]: Leaving directory '/c/opt/rtems/kernel/pc686' + /c/opt/rtems/kernel/pc696 + $ + +Install the kernel to our prefix: + +.. code-block:: shell + + /c/opt/rtems/kernel/pc686 + $ make install + Making install in tools/build + make[1]: Entering directory '/c/opt/rtems/kernel/pc686/tools/build' + make[2]: Entering directory '/c/opt/rtems/kernel/pc686/tools/build' + /usr/bin/mkdir -p '/c/opt/rtems/4.11/bin' + /usr/bin/install -c cklength.exe eolstrip.exe packhex.exe unhex.exe + rtems-bin2c.exe '/c/opt/rtems/4.11/bin' + /usr/bin/mkdir -p '/c/opt/rtems/4.11/bin' + /usr/bin/install -c install-if-change '/c/opt/rtems/4.11/bin' + make[2]: Nothing to be done for 'install-data-am'. + make[2]: Leaving directory '/c/opt/rtems/kernel/pc686/tools/build' + make[1]: Leaving directory '/c/opt/rtems/kernel/pc686/tools/build' + Making install in tools/cpu + make[1]: Entering directory '/c/opt/rtems/kernel/pc686/tools/cpu' + Making install in generic + make[2]: Entering directory '/c/opt/rtems/kernel/pc686/tools/cpu/generic' + make[3]: Entering directory '/c/opt/rtems/kernel/pc686/tools/cpu/generic' + make[3]: Nothing to be done for 'install-exec-am'. + make[3]: Nothing to be done for 'install-data-am'. + make[3]: Leaving directory '/c/opt/rtems/kernel/pc686/tools/cpu/generic' + make[2]: Leaving directory '/c/opt/rtems/kernel/pc686/tools/cpu/generic' + make[2]: Entering directory '/c/opt/rtems/kernel/pc686/tools/cpu' + make[3]: Entering directory '/c/opt/rtems/kernel/pc686/tools/cpu' + make[3]: Nothing to be done for 'install-exec-am'. + make[3]: Nothing to be done for 'install-data-am'. + .......... + make[2]: Entering directory '/c/opt/rtems/kernel/pc686' + make[2]: Nothing to be done for 'install-exec-am'. + /usr/bin/mkdir -p '/c/opt/rtems/4.11/make' + /usr/bin/install -c -m 644 /c/opt/rtems/kernel/rtems/make/main.cfg + /c/opt/rtems/kernel/rtems/make/leaf.cfg '/c/opt/rtems/4.11/make' + /usr/bin/mkdir -p '/c/opt/rtems/4.11/share/rtems4.11/make/Templates' + /usr/bin/install -c -m 644 + /c/opt/rtems/kernel/rtems/make/Templates/Makefile.dir + /c/opt/rtems/kernel/rtems/make/Templates/Makefile.leaf + /c/opt/rtems/kernel/rtems/make/Templates/Makefile.lib + '/c/opt/rtems/4.11/share/rtems4.11/make/Templates' + /usr/bin/mkdir -p '/c/opt/rtems/4.11/make/custom' + /usr/bin/install -c -m 644 /c/opt/rtems/kernel/rtems/make/custom/default.cfg + '/c/opt/rtems/4.11/make/custom' + make[2]: Leaving directory '/c/opt/rtems/kernel/pc686' + make[1]: Leaving directory '/c/opt/rtems/kernel/pc686' + /c/opt/rtems/kernel/pc686 + $ diff --git a/user/installation/index.rst b/user/installation/index.rst new file mode 100644 index 0000000..357fb8a --- /dev/null +++ b/user/installation/index.rst @@ -0,0 +1,47 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. comment: Copyright (c) 2016 Chris Johns <chrisj@rtems.org> +.. comment: All rights reserved. + +.. _installation: + +Installation +============ +.. index:: Installation + +This section details how to set up and install the RTEMS Ecosystem. You will +create a set of tools and an RTEMS kernel for your selected Board Support +Package (BSP). + +You will be asked to follow a few simple steps and when you have finished you +will have a development environment set up you can use to build applications +for RTEMS. You will have also created a development environment you and a team +can adapt for a project of any size and complexity. + +.. index:: Tools + +RTEMS applications are developed using cross-development tools running on a +development computer, more commonlly referred to as the host computer. These +are typically your desktop machine or a special build server. All RTEMS tools +and runtime libraries are built from source on your host machine. The RTEMS +Project does not maintain binary builds of the tools. This may appear to be the +opposite to what you normally experience with host operating systems, and it +is, however this approach works well. RTEMS is not a host operating system and +it is not a distrbution. Providing binary packages for every possible host +operating system is too big a task for the RTEMS Project and it is not a good +use of core developer time. Their time is better spent making RTEMS better and +faster. + +The RTEMS Project base installation set ups the tools and the RTEMS kernel for +the selected BSPs. The tools run on your host computer are used to compile, +link, and format executables so they can run on your target hardware. + +The RTEMS Project supports two set ups, release and developer +environments. Release installations create the tools and kernel in a single +pass ready for you to use. The tools and kernel are stable and only bug fixes +are added creating new dot point releases. The developer set up tracks the Git +repositories for the tools and kernel. + +.. include:: prefixes-sandboxing.rst +.. include:: releases.rst +.. include:: developer.rst diff --git a/user/installation/prefixes-sandboxing.rst b/user/installation/prefixes-sandboxing.rst new file mode 100644 index 0000000..c797a1f --- /dev/null +++ b/user/installation/prefixes-sandboxing.rst @@ -0,0 +1,151 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. comment: Copyright (c) 2016 Chris Johns <chrisj@rtems.org> +.. comment: All rights reserved. + +.. _prefixes: + +Prefixes +-------- + +.. index:: Prefixes + +You will see the term :ref:term:`prefix` referred to thoughout this +documentation and in a wide number of software packages you can download from +the internet. A **prefix** is the path on your computer a software package is +built and installed under. Packages that have a **prefix** will place all parts +under the **prefix** path. On a host computer like Linux the packages you +install from your distribution typically use a platform specific standard +**prefix**. For example on Linux it is :file:`/usr` and on FreeBSD it is +:file:`/usr/local`. + +We recommend you *DO NOT* use the standard **prefix** when installing the RTEMS +Tools. The standard **prefix** is the default **prefix** each package built by +the RSB contains. If you are building the tools when logged in as a *Standard +User* and not as the *Super User* (``root``) or *Administrator* the RTEMS +Source Builder (RSB) *will* fail and report an error if the default **prefix** +is not writable. We recommend you leave the standand **prefix** for the +packages your operating system installs or software you manually install such +as applications. + +A further reason not to use the standard **prefix** is to allow more than one +version of RTEMS to exist on your host machine at a time. The ``autoconf`` and +``automake`` tools required by RTEMS are not versioned and vary between the +various versions of RTEMS. If you use a single **prefix** such as the standard +**prefix** there is a chance parts from a package of different versions may +interact. This should not happen but it can. + +For POSIX or Unix hosts, the RTEMS Project uses :file:`/opt/rtems` as it's +standard **prefix**. We view this **prefix** as a production level path, and we +prefer to place development versions under a different **prefix** away from the +production versions. Under this top level **prefix** we place the various +versions we need for development. For example the version 4.11.0 **prefix** +would be :file:`/opt/rtems/4.11.0`. If an update called 4.11.1 is released the +**prefix** would be :file:`/opt/rtems/4.11.1`. These are recommendations and +the choice of what you use is entirely yours. You may decide to have a single +path for all RTEMS 4.11 releases of :file:`/opt/rtems/4.11`. + +For Windows a typical **prefix** is :file:`C:\\opt\\rtems` and as an MSYS2 path +this is :file:`/c/opt/rtems`. + +.. _project-sandboxing: + +Project Sandboxing +------------------ + +Project specific sandboxes let you have a number of projects running in +parallel with each project in its own sandbox. You simply have a +:ref:term:`prefix` per project and under that prefix you create a simple yet +repeatable structure. + +As an example lets say I have a large disk mounted under :file:`/bd` for *Big +Disk*. As ``root`` create a directory called ``projects`` and give the +directory suitable permissions to be writable by you as a user. + +Lets create a project sandbox for my *Box Sorter* project. First create a +project directory called :file:`/bd/projects/box-sorter`. Under this create +:file:`rtems` and under that create :file:`rtems-4.11.0`. Under this path you +can follow the :ref:`released-version` procedure to build a tool set using the +prefix of :file:`/bd/projects/box-sorter/rtems/4.11.0`. You are free to create +your project specific directories under :file:`/bd/projects/box-sorter`. The +top level directories would be: + +:file:`/bd/projects` + Project specific development trees. + +:file:`/bd/projects/box-sorter` + Box Sorter project sandbox. + +:file:`/bd/projects/box-sorter/rtems/4.11.0` + Project prefix for RTEMS 4.11.0 compiler, debuggers, tools and installed + Board Support Package (BSP). + +A variation is to use the ``--without-rtems`` option with the RSB to not build +the BSPs when building the tools and to build RTEMS specifically for each +project. This lets you have a production tools installed at a top level on your +disk and each project can have a specific and possibly customised version of +RTEMS. The top level directories would be: + +:file:`/bd/rtems` + The top path to production tools. + +:file:`/bd/rtems/4.11.0` + Production prefix for RTEMS 4.11.0 compiler, debuggers and tools. + +:file:`/bd/projects` + Project specific development trees. + +:file:`/bd/projects/box-sorter` + Box Sorter project sandbox. + +:file:`/bd/projects/box-sorter/rtems` + Box Sorter project's custom RTEMS kernel source and installed BSP. + +A further varation if there is an RTEMS kernel you want to share between +projects is it to move this to a top level and share. In this case you will end +up with: + +:file:`/bd/rtems` + The top path to production tools and kernels. + +:file:`/bd/rtems/4.11.0` + Production prefix for RTEMS 4.11.0. + +:file:`/bd/rtems/4.11.0/tools` + Production prefix for RTEMS 4.11.0 compiler, debuggers and tools. + +:file:`/bd/rtems/4.11.0/bsps` + Production prefix for RTEMS 4.11.0 Board Support Packages (BSPs). + +:file:`/bd/projects` + Project specific development trees. + +:file:`/bd/projects/box-sorter` + Box Sorter project sandbox. + +Finally you can have a single set of *production* tools and RTEMS BSPs on the +disk under :file:`/bd/rtems` you can share between your projects. The top level +directories would be: + +:file:`/bd/rtems` + The top path to production tools and kernels. + +:file:`/bd/rtems/4.11.0` + Production prefix for RTEMS 4.11.0 compiler, debuggers, tools and Board + Support Packages (BSPs). + +:file:`/bd/projects` + Project specific development trees. + +:file:`/bd/projects/box-sorter` + Box Sorter project sandbox. + +The project sandoxing approach allows you move a specific production part into +the project's sandbox to allow you to customise it. This is useful if you are +testing new releases. The typical dependency is the order listed above. You can +test new RTEMS kernels with production tools but new tools will require you +build the kernel with them. Release notes with each release will let know +what you need to update. + +If the machine is a central project development machine simply replace +:file:`projects` with :file:`users` and give each user a personal directory. diff --git a/user/installation/releases.rst b/user/installation/releases.rst new file mode 100644 index 0000000..ec458f2 --- /dev/null +++ b/user/installation/releases.rst @@ -0,0 +1,284 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. comment: Copyright (c) 2016 Chris Johns <chrisj@rtems.org> +.. comment: All rights reserved. + +.. _released-version: + +Releases +-------- +.. index:: tarball +.. index:: release + +RTEMS releases provide a stable version of the kernel for the supported +architectures. RTEMS maintaines the current and previous releases. Support for +older releases is provided using the RTEMS support channels. + +Please read :ref:`development-host` before continuing. The following procedure +assumes you have installed and configured your host operating. It also assumes +you have installed any dependent packages needed when building the tools and +the kernel. + +You need to select a location to build and install the RTEMS Tool chain and +RTEMS. Make sure there is plenty of disk space and a fast disk is +recommended. Our procedure will document building and installing the tools in a +base directory called :file:`/opt/rtems`. This path will require root +access. If you are working on a machine you do not have root access to you can +use a home directory, If building on Windows use :file:`/c/opt/rtems` to keep +the top level paths as short as possible. :ref:`windows-path-length` provides +more detail about path lengths on Windows. + +The location used to install the tools and kernel is called the +`prefix`. :ref:`prefixes` explains prefixes and how to use them. It is best to +have a `prefix` for each different version of RTEMS you are using. If you are +using RTEMS 4.11 in production it is **not** a good idea to install a +development version of 4.12 over the top by using the same `prefix` as the 4.11 +build. A separate `prefix` for each version avoids this. + +Released versions of the RTEMS Source Builder (RSB) downloads all source code +for all packages from the :r:url:`ftp` rather than from the package's home +site. Hosting all the source on the :r:url:`ftp` ensures the source is present +for the life of the release on the :r:url:`ftp`. If there is a problem +accessing the RTEMS FTP the RSB will fall back to the packages home site. + +The :r:url:`ftp` is hosted at the Oregon State University's The Open Source Lab +(http://osuosl.org/). This is a nonprofit organization working for the +advancement of open source technologies and RTEMS is very fortunate to be +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. + + 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 + RSB the option ``--with-rtemsbsp``. For example to build two BSPs for the + SPARC architecture you can supply ``--with-rtemsbsp="erc32 sis"``. This can + speed the build time up for some architectures that have a lot of BSPs. + +RTEMS Tools and Kernel +~~~~~~~~~~~~~~~~~~~~~~ + +This procedure will build a SPARC tool chain. Set up a suitable workspace to +build the release in. On Unix: + +.. code-block:: shell + + $ cd + $ mkdir -p development/rtems/releases + $ cd development/rtems/releases + +If building on Windows: + +.. code-block:: shell + + $ cd /c + $ mkdir -p opt/rtems + $ cd opt/rtems + +**Note** the paths on Windows will be different to those shown. + +Download the RTEMS Source Builder (RSB) from the RTEMS FTP server: + +.. code-block:: shell + + $ wget https://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/rtems-source-builder-4.11.0.tar.xz + --2016-03-21 10:50:04-- https://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/rtems-source-builder-4.11.0.tar.xz + Resolving ftp.rtems.org (ftp.rtems.org)... 140.211.10.151 + Connecting to ftp.rtems.org (ftp.rtems.org)|140.211.10.151|:443... connected. + HTTP request sent, awaiting response... 200 OK + Length: 967056 (944K) [application/x-xz] + Saving to: 'rtems-source-builder-4.11.0.tar.xz' + + rtems-source-builder-4.1 100%[====================================>] 944.39K 206KB/s in 5.5s + + 2016-03-21 10:50:11 (173 KB/s) - 'rtems-source-builder-4.11.0.tar.xz' saved [967056/967056] + +On Unix unpack the RSB release tar file using: + +.. code-block:: shell + + $ tar Jxf rtems-source-builder-4.11.0.tar.xz + $ cd rtems-source-builder-4.11.0/rtems/ + +On Windows you need to shorten the path (See :ref:`windows-path-length`) after +you have unpacked the tar file: + +.. code-block:: shell + + $ tar Jxf rtems-source-builder-4.11.0.tar.xz + $ mv rtems-source-builder-4.11.0 4.110 + $ cd 4.11.0 + +Build a tool chain for the SPARC architecure. We are using the SPARC +architecture in our example because GDB has a good simulator that lets us run +and test the samples RTEMS builds by default + +If building on Windows add ``--jobs=none`` to avoid GNU make issues on Windows +discussed in :ref:`msys2_parallel_builds`. + +.. code-block:: shell + + $ ../source-builder/sb-set-builder \ + --prefix=/opt/rtems/4.11 4.11/rtems-sparc + Build Set: 4.11/rtems-sparc + Build Set: 4.11/rtems-autotools.bset + Build Set: 4.11/rtems-autotools-internal.bset + config: tools/rtems-autoconf-2.69-1.cfg + package: autoconf-2.69-x86_64-freebsd10.1-1 + Creating source directory: sources + download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/autoconf-2.69.tar.gz -> sources/autoconf-2.69.tar.gz + downloading: sources/autoconf-2.69.tar.gz - 1.8MB of 1.8MB (100%) + building: autoconf-2.69-x86_64-freebsd10.1-1 + config: tools/rtems-automake-1.12.6-1.cfg + package: automake-1.12.6-x86_64-freebsd10.1-1 + download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/automake-1.12.6.tar.gz -> sources/automake-1.12.6.tar.gz + downloading: sources/automake-1.12.6.tar.gz - 2.0MB of 2.0MB (100%) + Creating source directory: patches + download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/automake-1.12.6-bugzilla.redhat.com-1239379.diff -> patches/automake-1.12.6-bugzilla.redhat.com-1239379.diff + downloading: patches/automake-1.12.6-bugzilla.redhat.com-1239379.diff - 408.0 bytes of 408.0 bytes (100%) + building: automake-1.12.6-x86_64-freebsd10.1-1 + cleaning: autoconf-2.69-x86_64-freebsd10.1-1 + cleaning: automake-1.12.6-x86_64-freebsd10.1-1 + Build Set: Time 0:00:32.749337 + Build Set: 4.11/rtems-autotools-base.bset + config: tools/rtems-autoconf-2.69-1.cfg + package: autoconf-2.69-x86_64-freebsd10.1-1 + building: autoconf-2.69-x86_64-freebsd10.1-1 + reporting: tools/rtems-autoconf-2.69-1.cfg -> autoconf-2.69-x86_64-freebsd10.1-1.txt + reporting: tools/rtems-autoconf-2.69-1.cfg -> autoconf-2.69-x86_64-freebsd10.1-1.xml + config: tools/rtems-automake-1.12.6-1.cfg + package: automake-1.12.6-x86_64-freebsd10.1-1 + building: automake-1.12.6-x86_64-freebsd10.1-1 + reporting: tools/rtems-automake-1.12.6-1.cfg -> automake-1.12.6-x86_64-freebsd10.1-1.txt + reporting: tools/rtems-automake-1.12.6-1.cfg -> automake-1.12.6-x86_64-freebsd10.1-1.xml + installing: autoconf-2.69-x86_64-freebsd10.1-1 -> /opt/work/rtems/4.11.0 + installing: automake-1.12.6-x86_64-freebsd10.1-1 -> /opt/work/rtems/4.11.0 + cleaning: autoconf-2.69-x86_64-freebsd10.1-1 + cleaning: automake-1.12.6-x86_64-freebsd10.1-1 + Build Set: Time 0:00:15.619219 + Build Set: Time 0:00:48.371085 + config: devel/expat-2.1.0-1.cfg + package: expat-2.1.0-x86_64-freebsd10.1-1 + download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/expat-2.1.0.tar.gz -> sources/expat-2.1.0.tar.gz + downloading: sources/expat-2.1.0.tar.gz - 549.4kB of 549.4kB (100%) + building: expat-2.1.0-x86_64-freebsd10.1-1 + reporting: devel/expat-2.1.0-1.cfg -> expat-2.1.0-x86_64-freebsd10.1-1.txt + reporting: devel/expat-2.1.0-1.cfg -> expat-2.1.0-x86_64-freebsd10.1-1.xml + config: tools/rtems-binutils-2.26-1.cfg + package: sparc-rtems4.11-binutils-2.26-x86_64-freebsd10.1-1 + download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/binutils-2.26.tar.bz2 -> sources/binutils-2.26.tar.bz2 + downloading: sources/binutils-2.26.tar.bz2 - 24.4MB of 24.4MB (100%) + building: sparc-rtems4.11-binutils-2.26-x86_64-freebsd10.1-1 + reporting: tools/rtems-binutils-2.26-1.cfg -> + sparc-rtems4.11-binutils-2.26-x86_64-freebsd10.1-1.txt + reporting: tools/rtems-binutils-2.26-1.cfg -> + sparc-rtems4.11-binutils-2.26-x86_64-freebsd10.1-1.xml + config: tools/rtems-gcc-4.9.3-newlib-2.2.0-20150423-1.cfg + package: sparc-rtems4.11-gcc-4.9.3-newlib-2.2.0.20150423-x86_64-freebsd10.1-1 + download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/gcc-4.9.3.tar.bz2 -> sources/gcc-4.9.3.tar.bz2 + downloading: sources/gcc-4.9.3.tar.bz2 - 85.8MB of 85.8MB (100%) + download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/newlib-2.2.0.20150423.tar.gz -> sources/newlib-2.2.0.20150423.tar.gz + downloading: sources/newlib-2.2.0.20150423.tar.gz - 16.7MB of 16.7MB (100%) + download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/mpfr-3.0.1.tar.bz2 -> sources/mpfr-3.0.1.tar.bz2 + downloading: sources/mpfr-3.0.1.tar.bz2 - 1.1MB of 1.1MB (100%) + download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/mpc-0.8.2.tar.gz -> sources/mpc-0.8.2.tar.gz + downloading: sources/mpc-0.8.2.tar.gz - 535.5kB of 535.5kB (100%) + download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/gmp-5.0.5.tar.bz2 -> sources/gmp-5.0.5.tar.bz2 + downloading: sources/gmp-5.0.5.tar.bz2 - 2.0MB of 2.0MB (100%) + building: sparc-rtems4.11-gcc-4.9.3-newlib-2.2.0.20150423-x86_64-freebsd10.1-1 + reporting: tools/rtems-gcc-4.9.3-newlib-2.2.0-20150423-1.cfg -> + sparc-rtems4.11-gcc-4.9.3-newlib-2.2.0.20150423-x86_64-freebsd10.1-1.txt + reporting: tools/rtems-gcc-4.9.3-newlib-2.2.0-20150423-1.cfg -> + sparc-rtems4.11-gcc-4.9.3-newlib-2.2.0.20150423-x86_64-freebsd10.1-1.xml + config: tools/rtems-gdb-7.9-1.cfg + package: sparc-rtems4.11-gdb-7.9-x86_64-freebsd10.1-1 + download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/gdb-7.9.tar.xz -> sources/gdb-7.9.tar.xz + downloading: sources/gdb-7.9.tar.xz - 17.0MB of 17.0MB (100%) + download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0001-sim-erc32-Disassembly-in-stand-alone-mode-did-not-wo.patch -> patches/0001-sim-erc32-Disassembly-in-stand-alone-mode-did-not-wo.patch + downloading: patches/0001-sim-erc32-Disassembly-in-stand-alone-mode-did-not-wo.patch - 1.9kB of 1.9kB (100%) + download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0002-sim-erc32-Corrected-wrong-CPU-implementation-and-ver.patch -> patches/0002-sim-erc32-Corrected-wrong-CPU-implementation-and-ver.patch + downloading: patches/0002-sim-erc32-Corrected-wrong-CPU-implementation-and-ver.patch - 827.0 bytes of 827.0 bytes (100%) + download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0003-sim-erc32-Perform-pseudo-init-if-binary-linked-to-no.patch -> patches/0003-sim-erc32-Perform-pseudo-init-if-binary-linked-to-no.patch + downloading: patches/0003-sim-erc32-Perform-pseudo-init-if-binary-linked-to-no.patch - 2.6kB of 2.6kB (100%) + download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0004-sim-erc32-Use-fenv.h-for-host-FPU-access.patch -> patches/0004-sim-erc32-Use-fenv.h-for-host-FPU-access.patch + downloading: patches/0004-sim-erc32-Use-fenv.h-for-host-FPU-access.patch - 4.9kB of 4.9kB (100%) + download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0005-sim-erc32-Remove-unused-defines-in-Makefile-and-swit.patch -> patches/0005-sim-erc32-Remove-unused-defines-in-Makefile-and-swit.patch + downloading: patches/0005-sim-erc32-Remove-unused-defines-in-Makefile-and-swit.patch - 871.0 bytes of 871.0 bytes (100%) + download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0006-sim-erc32-Fix-incorrect-simulator-performance-report.patch -> patches/0006-sim-erc32-Fix-incorrect-simulator-performance-report.patch + downloading: patches/0006-sim-erc32-Fix-incorrect-simulator-performance-report.patch - 5.6kB of 5.6kB (100%) + download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0007-sim-erc32-File-loading-via-command-line-did-not-work.patch -> patches/0007-sim-erc32-File-loading-via-command-line-did-not-work.patch + downloading: patches/0007-sim-erc32-File-loading-via-command-line-did-not-work.patch - 1.0kB of 1.0kB (100%) + download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0008-sim-erc32-Added-v-command-line-switch-for-verbose-ou.patch -> patches/0008-sim-erc32-Added-v-command-line-switch-for-verbose-ou.patch + downloading: patches/0008-sim-erc32-Added-v-command-line-switch-for-verbose-ou.patch - 3.6kB of 3.6kB (100%) + download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0009-sim-erc32-Removed-type-mismatch-compiler-warnings.patch -> patches/0009-sim-erc32-Removed-type-mismatch-compiler-warnings.patch + downloading: patches/0009-sim-erc32-Removed-type-mismatch-compiler-warnings.patch - 1.9kB of 1.9kB (100%) + download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0010-sim-erc32-Switched-emulated-memory-to-host-endian-or.patch -> patches/0010-sim-erc32-Switched-emulated-memory-to-host-endian-or.patch + downloading: patches/0010-sim-erc32-Switched-emulated-memory-to-host-endian-or.patch - 16.0kB of 16.0kB (100%) + download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0011-sim-erc32-use-SIM_AC_OPTION_HOSTENDIAN-to-probe-for-.patch -> patches/0011-sim-erc32-use-SIM_AC_OPTION_HOSTENDIAN-to-probe-for-.patch + downloading: patches/0011-sim-erc32-use-SIM_AC_OPTION_HOSTENDIAN-to-probe-for-.patch - 14.8kB of 14.8kB (100%) + download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0012-sim-erc32-Use-memory_iread-function-for-instruction-.patch -> patches/0012-sim-erc32-Use-memory_iread-function-for-instruction-.patch + downloading: patches/0012-sim-erc32-Use-memory_iread-function-for-instruction-.patch - 3.8kB of 3.8kB (100%) + download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0013-sim-erc32-Fix-a-few-compiler-warnings.patch-> patches/0013-sim-erc32-Fix-a-few-compiler-warnings.patch + downloading: patches/0013-sim-erc32-Fix-a-few-compiler-warnings.patch - 2.2kB of 2.2kB (100%) + download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0014-sim-erc32-Use-gdb-callback-for-UART-I-O-when-linked-.patch -> patches/0014-sim-erc32-Use-gdb-callback-for-UART-I-O-when-linked-.patch + downloading: patches/0014-sim-erc32-Use-gdb-callback-for-UART-I-O-when-linked-.patch - 9.2kB of 9.2kB (100%) + download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0015-sim-erc32-Access-memory-subsystem-through-struct-mem.patch -> patches/0015-sim-erc32-Access-memory-subsystem-through-struct-mem.patch + downloading: patches/0015-sim-erc32-Access-memory-subsystem-through-struct-mem.patch - 22.9kB of 22.9kB (100%) + download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0016-sim-erc32-Use-readline.h-for-readline-types-and-func.patch -> patches/0016-sim-erc32-Use-readline.h-for-readline-types-and-func.patch + downloading: patches/0016-sim-erc32-Use-readline.h-for-readline-types-and-func.patch - 1.5kB of 1.5kB (100%) + download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0017-sim-erc32-Move-local-extern-declarations-into-sis.h.patch -> patches/0017-sim-erc32-Move-local-extern-declarations-into-sis.h.patch + downloading: patches/0017-sim-erc32-Move-local-extern-declarations-into-sis.h.patch - 5.8kB of 5.8kB (100%) + download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0018-sim-erc32-Add-support-for-LEON3-processor-emulation.patch -> patches/0018-sim-erc32-Add-support-for-LEON3-processor-emulation.patch + downloading: patches/0018-sim-erc32-Add-support-for-LEON3-processor-emulation.patch - 66.7kB of 66.7kB (100%) + download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0019-sim-erc32-Add-support-for-LEON2-processor-emulation.patch -> patches/0019-sim-erc32-Add-support-for-LEON2-processor-emulation.patch + downloading: patches/0019-sim-erc32-Add-support-for-LEON2-processor-emulation.patch - 26.1kB of 26.1kB (100%) + download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0020-sim-erc32-Updated-documentation.patch -> patches/0020-sim-erc32-Updated-documentation.patch + downloading: patches/0020-sim-erc32-Updated-documentation.patch - 16.1kB of 16.1kB (100%) + download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0021-sim-erc32-Add-data-watchpoint-support.patch -> patches/0021-sim-erc32-Add-data-watchpoint-support.patch + downloading: patches/0021-sim-erc32-Add-data-watchpoint-support.patch - 10.1kB of 10.1kB (100%) + download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0022-Add-watchpoint-support-to-gdb-simulator-interface.patch -> patches/0022-Add-watchpoint-support-to-gdb-simulator-interface.patch + downloading: patches/0022-Add-watchpoint-support-to-gdb-simulator-interface.patch - 25.5kB of 25.5kB (100%) + download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0023-sim-erc32-ELF-loading-could-fail-on-unaligned-sectio.patch -> patches/0023-sim-erc32-ELF-loading-could-fail-on-unaligned-sectio.patch + downloading: patches/0023-sim-erc32-ELF-loading-could-fail-on-unaligned-sectio.patch - 1.3kB of 1.3kB (100%) + download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/gdb-sim-arange-inline.diff -> patches/gdb-sim-arange-inline.diff + downloading: patches/gdb-sim-arange-inline.diff - 761.0 bytes of 761.0 bytes (100%) + download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/gdb-sim-cgen-inline.diff -> patches/gdb-sim-cgen-inline.diff + downloading: patches/gdb-sim-cgen-inline.diff - 706.0 bytes of 706.0 bytes (100%) + download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/patch-gdb-python-python-config.py -> patches/patch-gdb-python-python-config.py + downloading: patches/patch-gdb-python-python-config.py - 449.0 bytes of 449.0 bytes (100%) + building: sparc-rtems4.11-gdb-7.9-x86_64-freebsd10.1-1 + reporting: tools/rtems-gdb-7.9-1.cfg -> + sparc-rtems4.11-gdb-7.9-x86_64-freebsd10.1-1.txt + reporting: tools/rtems-gdb-7.9-1.cfg -> + sparc-rtems4.11-gdb-7.9-x86_64-freebsd10.1-1.xml + config: tools/rtems-tools-4.11-1.cfg + package: rtems-tools-4.11.0-1 + download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/rtems-tools-4.11.0.tar.xz -> sources/rtems-tools-4.11.0.tar.xz + downloading: sources/rtems-tools-4.11.0.tar.xz - 1.6MB of 1.6MB (100%) + building: rtems-tools-4.11.0-1 + reporting: tools/rtems-tools-4.11-1.cfg -> rtems-tools-4.11.0-1.txt + reporting: tools/rtems-tools-4.11-1.cfg -> rtems-tools-4.11.0-1.xml + config: tools/rtems-kernel-4.11.cfg + package: sparc-rtems4.11-kernel-4.11.0-1 + download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/rtems-4.11.0.tar.xz -> sources/rtems-4.11.0.tar.xz + downloading: sources/rtems-4.11.0.tar.xz - 9.3MB of 9.3MB (100%) + building: sparc-rtems4.11-kernel-4.11.0-1 + reporting: tools/rtems-kernel-4.11.cfg -> sparc-rtems4.11-kernel-4.11.0-1.txt + reporting: tools/rtems-kernel-4.11.cfg -> sparc-rtems4.11-kernel-4.11.0-1.xml + installing: expat-2.1.0-x86_64-freebsd10.1-1 -> /opt/work/rtems/4.11.0 + installing: sparc-rtems4.11-binutils-2.26-x86_64-freebsd10.1-1 -> /opt/work/rtems/4.11.0 + installing: sparc-rtems4.11-gcc-4.9.3-newlib-2.2.0.20150423-x86_64-freebsd10.1-1 -> /opt/work/rtems/4.11.0 + installing: sparc-rtems4.11-gdb-7.9-x86_64-freebsd10.1-1 -> /opt/work/rtems/4.11.0 + installing: rtems-tools-4.11.0-1 -> /opt/work/rtems/4.11.0 + installing: sparc-rtems4.11-kernel-4.11.0-1 -> /opt/work/rtems/4.11.0 + cleaning: expat-2.1.0-x86_64-freebsd10.1-1 + cleaning: sparc-rtems4.11-binutils-2.26-x86_64-freebsd10.1-1 + cleaning: sparc-rtems4.11-gcc-4.9.3-newlib-2.2.0.20150423-x86_64-freebsd10.1-1 + cleaning: sparc-rtems4.11-gdb-7.9-x86_64-freebsd10.1-1 + cleaning: rtems-tools-4.11.0-1 + 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. |