From 32ba27b678cfb8164ce39f087cf4e14e730e24c4 Mon Sep 17 00:00:00 2001 From: pritishjain Date: Wed, 21 Nov 2018 23:06:38 +0530 Subject: [PATCH] Closes Ticket #2562 docs: add version number guidelines and quick start output --- user/start/index.rst | 163 ++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 154 insertions(+), 9 deletions(-) diff --git a/user/start/index.rst b/user/start/index.rst index 1016678..3294a93 100644 --- a/user/start/index.rst +++ b/user/start/index.rst @@ -21,6 +21,8 @@ The short version of this procedure is as follows #. Create a workspace (:ref:`installation`), +#. RTEMS Release 5 and Higher version numbers, + #. Download the RTEMS Source Builder (RSB), #. Build an RTEMS tool chain for a specific target architecture, @@ -49,6 +51,43 @@ 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. +RTEMS Release 5 and Higher version numbers +========================================== +RTEMS includes its version numbers in different commands to build tools +specific to a particular versions. You will see that in coming examples, to +enable ourselves to make these tools properly we must learn how RTEMS +Release and version numbers work. Let us start with the terminology *release*. + +*RELEASE TERMINOLOGY* +A release is the creation of any generated files and their packaging +together with the source in a repository that makes the package available +as a file. +A release branch is a git branch pushed to the repositories. +A release branch release is a git tag on a release branch with +the tags pushed to the repositories. + +The numbering of RTEMS releases and versions goes like this. +The master branch has the version **N.0.0** with N being the next major release +number. The first release of this series will have the version number **N.1.0.** +There will be exactly one commit with this version number in the corresponding +repository. The first bugfix release (minor release) of this series will have +the version number **N.2.0**. The release branch will have the version +number **N.M.1** with **M** being the last minor release of this series. +You will better understand with this example: + ++ 5.0.0 is the version number of the development master for the 5 series. ++ 5.1.0 is the first release of the 5 series. ++ 5.1.1 is the version number of the 5 series release branch right after + the 5.1.0 release until 5.2.0 is released. ++ 5.2.0 is the first bugfix release of the 5 series ++ 5.2.1 is the version number of the 5 series release branch right after + the 5.2.0 release until 5.3.0 is released. ++ 6.0.0 is the version number of the development master for the 6 series. + +Tools will use **N** as the version number and must work with all releases and +the release branch of the N series. So to build tools for version number 5.1.0 +use 5 which is the **N** here . + Simple Example ============== @@ -58,14 +97,42 @@ Simple Example $ mkdir -p development/rtems $ cd development/rtems $ git clone git://git.rtems.org/rtems-source-builder.git rsb - ... + Cloning into 'rsb'... + remote: Counting objects: 8517, done. + remote: Compressing objects: 100% (4981/4981), done. + remote: Total 8517 (delta 5906), reused 5029 (delta 3494) + Receiving objects: 100% (8517/8517), 2.86 MiB | 136.00 KiB/s, done. + Resolving deltas: 100% (5906/5906), done. + Checking out files: 100% (436/436), done. $ cd rsb $ ./source-builder/sb-check - ... + RTEMS Source Builder - Check, 5 (77a00753035c) + Environment is ok $ cd rtems $ ../source-builder/sb-set-builder \ - --prefix=/usr/home/chris/development/rtems/5 5/rtems-sparc - ... + > --prefix=/usr/home/chris/development/rtems/5 5/rtems-sparc + RTEMS Source Builder - Set Builder, 5 (089327b5dcf9) + Build Set: 5/rtems-sparc + Build Set: 5/rtems-autotools.bset + Build Set: 5/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 + ..... + installing: sparc-rtems5-kernel-5-1 -> /usr/home/chris/development/rtems/5 + cleaning: expat-2.1.0-x86_64-linux-gnu-1 + cleaning: sparc-rtems5-binutils-2.29-x86_64-linux-gnu-1 + cleaning: sparc-rtems5-gcc-7.2.0-newlib-2.5.0.20170922-x86_64-linux-gnu-1 + cleaning: sparc-rtems5-gdb-8.0.1-x86_64-linux-gnu-1 + cleaning: rtems-tools-HEAD-1 + cleaning: sparc-rtems5-kernel-5-1 + Build Set: Time 0:39:33.988995 + + Build the RTEMS Kernel (:ref:`rtems-kernel-install`) by cloning the repository, running the ``bootstrap`` procecure, building and finally installing the @@ -79,18 +146,96 @@ kernel: $ mkdir kernel $ cd kernel $ git clone git://git.rtems.org/rtems.git rtems - ... + Cloning into 'rtems'... + remote: Counting objects: 547391, done. + remote: Compressing objects: 100% (97632/97632), done. + remote: Total 547391 (delta 440626), reused 542940 (delta 437336) + Receiving objects: 100% (547391/547391), 79.23 MiB | 226.00 KiB/s, done. + Resolving deltas: 100% (440626/440626), done. + Checking out files: 100% (9588/9588), done. $ cd rtems $ ./bootstrap -c && $HOME/development/rtems/rsb/source-builder/sb-bootstrap - ... + removing automake generated Makefile.in files + removing configure files + removing aclocal.m4 files + RTEMS Source Builder - RTEMS Bootstrap, 5 (77a00753035c) + 1/119: autoreconf: configure.ac + 2/119: autoreconf: c/configure.ac + 3/119: autoreconf: c/src/configure.ac + .... + 118/119: autoreconf: testsuites/sptests/configure.ac + 119/119: autoreconf: testsuites/tmtests/configure.ac + Bootstrap time: 1:35:32.674502 $ cd .. $ mkdir erc32 $ cd erc32 $ $HOME/development/rtems/kernel/rtems/configure --prefix=$HOME/development/rtems/5 \ - --target=sparc-rtems5 --enable-rtemsbsp=erc32 --enable-posix - ... + > --target=sparc-rtems5 --enable-rtemsbsp=erc32 --enable-posix + configure: loading site script /mingw64/etc/config.site + checking for gmake... no + checking for make... make + checking for RTEMS Version... 5.0.0 + checking build system type... x86_64-w64-mingw32 + .... + target architecture: sparc. + available BSPs: erc32. + 'make all' will build the following BSPs: erc32. + other BSPs can be built with 'make RTEMS_BSP="bsp1 bsp2 ..."' + + config.status: creating Makefile + $ make -j 8 - ... + Making all in sparc-rtems5/c + make[1]: Entering directory '/d/development/rtems/kernel/erc32/sparc-rtems5/c' + Making all in . + make[2]: Entering directory '/d/development/rtems/kernel/erc32/sparc-rtems5/c' + Configuring RTEMS_BSP=erc32 + configure: loading site script /mingw64/etc/config.site + checking for gmake... no + checking for make... make + checking build system type... x86_64-w64-mingw32 + checking host system type... sparc-unknown-rtems5 + checking rtems target cpu... sparc + checking for a BSD-compatible install... /usr/bin/install -c + checking whether build environment is sane... yes + checking for sparc-rtems5-strip... sparc-rtems5-strip + 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 for RTEMS_BSP... erc32 + checking whether CPU supports libposix... yes + .... + libbsp/sparc/erc32/librtemsbsp.a ./../../cpukit/librtemscpu.a + make[5]: Leaving directory '/d/development/rtems/kernel/erc32/sparc-rtems5/c/erc32/testsuites/samples' + make[4]: Leaving directory '/d/development/rtems/kernel/erc32/sparc-rtems5/c/erc32/testsuites' + make[3]: Leaving directory '/d/development/rtems/kernel/erc32/sparc-rtems5/c/erc32' + make[2]: Leaving directory '/d/development/rtems/kernel/erc32/sparc-rtems5/c/erc32' + make[1]: Leaving directory '/d/development/rtems/kernel/erc32/sparc-rtems5/c' + make[1]: Entering directory '/d/development/rtems/kernel/erc32' + make[1]: Nothing to be done for 'all-am'. + make[1]: Leaving directory '/d/development/rtems/kernel/erc32' + $ make install + Making install in sparc-rtems5/c + make[1]: Entering directory '/d/development/rtems/kernel/erc32/sparc-rtems5/c' + Making install in . + make[2]: Entering directory '/d/development/rtems/kernel/erc32/sparc-rtems5/c' + make[3]: Entering directory '/d/development/rtems/kernel/erc32/sparc-rtems5/c' + make[3]: Nothing to be done for 'install-exec-am'. + make[3]: Nothing to be done for 'install-data-am'. + make[3]: Leaving directory '/d/development/rtems/kernel/erc32/sparc-rtems5/c' + make[2]: Leaving directory '/d/development/rtems/kernel/erc32/sparc-rtems5/c' + Making install in erc32 + .... + /usr/bin/install -c -m 644 /d/development/rtems/kernel/rtems/make/main.cfg /d/development/rtems/kernel/rtems/make/leaf.cfg '/d/development/rtems/5/make' + /usr/bin/mkdir -p '/d/development/rtems/5/share/rtems5/make/Templates' + /usr/bin/install -c -m 644 /d/development/rtems/kernel/rtems/make/Templates/Makefile.dir /d/development/rtems/kernel/rtems/make/Templates/Makefile.leaf /d/development/rtems/kernel/rtems/make/Templates/Makefile.lib '/d/development/rtems/5/share/rtems5/make/Templates' + /usr/bin/mkdir -p '/d/development/rtems/5/make/custom' + /usr/bin/install -c -m 644 /d/development/rtems/kernel/rtems/make/custom/default.cfg '/d/development/rtems/5/make/custom' + make[2]: Leaving directory '/d/development/rtems/kernel/erc32' + make[1]: Leaving directory '/d/development/rtems/kernel/erc32' + + You can now build a 3rd party library or an application. -- 2.19.1