source: rtems-docs/rsb/project-sets.rst @ e52906b

5
Last change on this file since e52906b was e52906b, checked in by Sebastian Huber <sebastian.huber@…>, on 01/09/19 at 15:14:06

Simplify SPDX-License-Identifier comment

  • Property mode set to 100644
File size: 10.6 KB
Line 
1.. SPDX-License-Identifier: CC-BY-SA-4.0
2
3.. Copyright (C) 2012, 2016 Chris Johns <chrisj@rtems.org>
4
5Project Sets
6============
7
8The RTEMS Source Builder supports project configurations. Project
9configurations can be public or private and can be contained in the RTEMS
10Source Builder project if suitable, other projects they use the RTEMS Source
11Builder or privately on your local file system.
12
13The configuration file loader searches the macro ``_configdir`` and by default
14this is set to ``%{_topdir}/config:%{_sbdir}/config`` where ``_topdir`` is the
15your current working direct, in other words the directory you invoke the RTEMS
16Source Builder command in, and ``_sbdir`` is the directory where the RTEMS
17Source Builder command resides. Therefore the ``config`` directory under each
18of these is searched so all you need to do is create a ``config`` in your
19project and add your configuration files. They do not need to be under the
20RTEMS Source Builder source tree. Public projects are included in the main
21RTEMS Source Builder such as RTEMS.
22
23You can also add your own ``patches`` directory next to your ``config``
24directory as the ``%patch`` command searches the ``_patchdir`` macro variable
25and it is by default set to ``%{_topdir}/patches:%{_sbdir}/patches``.
26
27The ``source-builder/config`` directory provides generic scripts for building
28various tools. You can specialise these in your private configurations to make
29use of them. If you add new generic configurations please contribute them back
30to the project
31
32Bare Metal
33----------
34
35The RSB contains a 'bare' configuration tree and you can use this to add
36packages you use on the hosts. For example 'qemu' is supported on a range of
37hosts. RTEMS tools live in the ``rtems/config`` directory tree. RTEMS packages
38include tools for use on your host computer as well as packages you can build
39and run on RTEMS.
40
41The **bare metal** support for GNU Tool chains. An example is the
42``lang/gcc491`` build set. You need to provide a target via the command line
43``--target`` option and this is in the standard 2 or 3 tuple form. For example
44for an ARM compiler you would use ``arm-eabi`` or ``arm-eabihf`, and for SPARC
45you would use `sparc-elf`::
46
47    $ cd rtems-source-builder/bare
48    $ ../source-builder/sb-set-builder --log=log_arm_eabihf \
49        --prefix=$HOME/development/bare --target=arm-eabihf lang/gcc491
50    RTEMS Source Builder - Set Builder, v0.3.0
51    Build Set: lang/gcc491
52    config: devel/expat-2.1.0-1.cfg
53    package: expat-2.1.0-x86_64-apple-darwin13.2.0-1
54    building: expat-2.1.0-x86_64-apple-darwin13.2.0-1
55    config: devel/binutils-2.24-1.cfg
56    package: arm-eabihf-binutils-2.24-1
57    building: arm-eabihf-binutils-2.24-1
58    config: devel/gcc-4.9.1-newlib-2.1.0-1.cfg
59    package: arm-eabihf-gcc-4.9.1-newlib-2.1.0-1
60    building: arm-eabihf-gcc-4.9.1-newlib-2.1.0-1
61    config: devel/gdb-7.7-1.cfg
62    package: arm-eabihf-gdb-7.7-1
63    building: arm-eabihf-gdb-7.7-1
64    installing: expat-2.1.0-x86_64-apple-darwin13.2.0-1 -> /Users/chris/development/bare
65    installing: arm-eabihf-binutils-2.24-1 -> /Users/chris/development/bare
66    installing: arm-eabihf-gcc-4.9.1-newlib-2.1.0-1 -> /Users/chris/development/bare
67    installing: arm-eabihf-gdb-7.7-1 -> /Users/chris/development/bare
68    cleaning: expat-2.1.0-x86_64-apple-darwin13.2.0-1
69    cleaning: arm-eabihf-binutils-2.24-1
70    cleaning: arm-eabihf-gcc-4.9.1-newlib-2.1.0-1
71    cleaning: arm-eabihf-gdb-7.7-1
72
73RTEMS
74-----
75
76The RTEMS Configurations found in the ``rtems`` directory. The configurations
77are grouped by RTEMS version. In RTEMS the tools are specific to a specific
78version because of variations between Newlib and RTEMS. Restructuring in RTEMS
79and Newlib sometimes moves *libc* functionality between these two parts and
80this makes existing tools incompatible with RTEMS.
81
82RTEMS allows architectures to have different tool versions and patches. The
83large number of architectures RTEMS supports can make it difficult to get a
84common stable version of all the packages. An architecture may require a recent
85GCC because an existing bug has been fixed, however the more recent version may
86have a bug in other architecture. Architecture specific patches should be
87limited to the architecture it relates to. The patch may fix a problem on the
88effect architecture however it could introduce a problem in another
89architecture. Limit exposure limits any possible crosstalk between
90architectures.
91
92If you are building a released version of RTEMS the release RTEMS tar file will
93be downloaded and built as part of the build process. If you are building a
94tool set for use with the development branch of RTEMS, the development branch
95will be cloned directly from the RTEMS GIT repository and built.
96
97When building RTEMS within the RTEMS Source Builder it needs a suitable working
98``autoconf`` and ``automake``. These packages need to built and installed in their
99prefix in order for them to work. The RTEMS Source Builder installs all
100packages only after they have been built so if you host does not have a
101recent enough version of ``autoconf`` and ``automake`` you first need to build them
102and install them then build your tool set. The commands are::
103
104    $ ../source-builder/sb-set-builder --log=l-4.11-at.txt \
105       --prefix=$HOME/development/rtems/4.11 4.11/rtems-autotools
106    $ export PATH=~/development/rtems/4.11/bin:$PATH    <1>
107    $ ../source-builder/sb-set-builder --log=l-4.11-sparc.txt \
108       --prefix=$HOME/development/rtems/4.11 4.11/rtems-sparc
109
110.. topic:: Items:
111
112  1. Setting the path.
113
114If this is your first time building the tools and RTEMS it pays to add the
115``--dry-run`` option. This will run through all the configuration files and if
116any checks fail you will see this quickly rather than waiting for until the
117build fails a check.
118
119To build snapshots for testing purposes you use the available macro maps
120passing them on the command line using the ``--macros`` option. For RTEMS these
121are held in ``config/snapshots`` directory. The following builds *newlib* from
122CVS::
123
124    $ ../source-builder/sb-set-builder --log=l-4.11-sparc.txt \
125       --prefix=$HOME/development/rtems/4.11 \
126       --macros=snapshots/newlib-head.mc \
127       4.11/rtems-sparc
128
129and the following uses the version control heads for ``binutils``, ``gcc``,
130``newlib``, ``gdb`` and *RTEMS*::
131
132    $ ../source-builder/sb-set-builder --log=l-heads-sparc.txt \
133       --prefix=$HOME/development/rtems/4.11-head \
134       --macros=snapshots/binutils-gcc-newlib-gdb-head.mc \
135       4.11/rtems-sparc
136
137Patches
138-------
139
140Packages being built by the RSB need patches from time to time and the RSB
141supports patching upstream packages. The patches are held in a seperate
142directory called ``patches`` relative to the configuration directory you are
143building. For example ``%{_topdir}/patches:%{_sbdir}/patches``. Patches are
144declared in the configuration files in a similar manner to the package's source
145so please refer to the ``%source`` documentation. Patches, like the source, are
146to be made publically available for configurations that live in the RSB package
147and are downloaded on demand.
148
149If a package has a patch management tool it is recommended you reference the
150package's patch management tools directly. If the RSB does not support the
151specific patch manage tool please contact the mailing list to see if support
152can be added.
153
154Patches for packages developed by the RTEMS project can be placed in the RTEMS
155Tools Git repository. The ``tools`` directory in the repository has various
156places a patch can live. The tree is broken down in RTEMS releases and then
157tools within that release. If the package is not specific to any release the
158patch can be added closer to the top under the package's name. Patches to fix
159specific tool related issues for a specific architecture should be grouped
160under the specific architecture and only applied when building that
161architecture avoiding a patch breaking an uneffected architecture.
162
163Patches in the RTEMS Tools repository need to be submitted to the upstream
164project. It should not be a clearing house for patches that will not be
165accepted upstream.
166
167Patches are added to a component's name and in the ``%prep:`` section the
168patches can be set up, meaning they are applied to source. The patches
169are applied in the order they are added. If there is a dependency make
170sure you order the patches correctly when you add them. You can add any
171number of patches and the RSB will handle them efficently.
172
173Patches can have options. These are added before the patch URL. If no options
174are provided the patch's setup default options are used.
175
176Patches can be declared in build set up files.
177
178This examples shows how to declare a patch for gdb in the ``lm32`` architecture::
179
180    %patch add <1> gdb <2> %{rtems_gdb_patches}/lm32/gdb-sim-lm32uart.diff <3>
181
182.. topic:: Items:
183
184  1. The patch's ``add`` command.
185
186  2. The group of patches this patch belongs too.
187
188  3. The patch's URL. It is downloaded from here.
189
190Patches require a checksum to avoid a warning. The ``%hash`` directive can be
191used to add a checksum for a patch that is used to verify the patch::
192
193    %hash md5 <1> gdb-sim-lm32uart.diff <2> 77d070878112783292461bd6e7db17fb <3>
194
195.. topic:: Items:
196
197  1. The type of checksum, in the case an MD5 hash.
198
199  2. The patch file the checksum is for.
200
201  3. The MD5 hash.
202
203The patches are applied when a patch ``setup`` command is issued in the
204``%prep:`` section. All patches in the group are applied. To apply the GDB
205patch above use::
206
207    %patch setup <1> gdb <2> -p1 <3>
208
209.. topic:: Items:
210
211  1. The patch's ``setup`` command.
212
213  2. The group of patches to apply.
214
215  3. The patch group's default options. If no option is given with the patch
216     these options are used.
217
218Architecture specific patches live in the architecture build set file isolating
219the patch to that specific architecture. If a patch is common to a tool it
220resides in the RTEMS tools configuration file. Do not place patches for tools
221in the ``source-builder/config`` template configuration files.
222
223To test a patch simply copy it to your local ``patches`` directory. The RSB
224will see the patch is present and will not attempt to download it. Once you are
225happy with the patch submit it to the project and a core developer will review
226it and add it to the RTEMS Tools git repository.  For example, to test a local
227patch for newlib, add the following two lines to the .cfg file in
228``rtems/config/tools/`` that is included by the bset you use:
229
230.. code-block:: auto
231
232    %patch add newlib file://0001-this-is-a-newlib-patch.patch   <1>
233    %hash md5 0001-this-is-a-newlib-patch.diff 77d070878112783292461bd6e7db17fb <2>
234
235.. topic:: Items:
236
237  1. The diff file prepended with ``file://`` to tell RSB this is a local file.
238
239  2. The output from md5sum on the diff file.
Note: See TracBrowser for help on using the repository browser.