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

Last change on this file since 3605600 was 3605600, checked in by Vaibhav Gupta <vaibhavgupta40@…>, on Aug 12, 2019 at 6:55:17 AM

Add steps to test Newlib patch.

Update the checksum to be used for the Newlib patches.
Earlier it was msd5, but it is depreciated for security
reasons. Now RSB accepts sha512.

  • Property mode set to 100644
File size: 12.6 KB
RevLine 
[e52906b]1.. SPDX-License-Identifier: CC-BY-SA-4.0
[8b64335]2
[4886d60]3.. Copyright (C) 2012, 2016 Chris Johns <chrisj@rtems.org>
[8b64335]4
5Project Sets
[2674d6a]6------------
[8b64335]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
[f95699b]32Build sets can be controlled via the command line to enable
33(``--with-<feature>``) and disable (``--without-<feature>``) various features.
34There is no definitive list of build options that can be listed because they
35are implemented with the configuration scripts.  The best way to find what is
36available is to grep the configuration files for ``with`` and ``without``.
37
[8b64335]38Bare Metal
[2674d6a]39^^^^^^^^^^
[8b64335]40
41The RSB contains a 'bare' configuration tree and you can use this to add
42packages you use on the hosts. For example 'qemu' is supported on a range of
43hosts. RTEMS tools live in the ``rtems/config`` directory tree. RTEMS packages
44include tools for use on your host computer as well as packages you can build
45and run on RTEMS.
46
47The **bare metal** support for GNU Tool chains. An example is the
48``lang/gcc491`` build set. You need to provide a target via the command line
49``--target`` option and this is in the standard 2 or 3 tuple form. For example
[2674d6a]50for an ARM compiler you would use ``arm-eabi`` or ``arm-eabihf``, and for SPARC
51you would use ``sparc-elf``:
52
[d5b631f]53.. code-block:: none
[8b64335]54
55    $ cd rtems-source-builder/bare
56    $ ../source-builder/sb-set-builder --log=log_arm_eabihf \
57        --prefix=$HOME/development/bare --target=arm-eabihf lang/gcc491
58    RTEMS Source Builder - Set Builder, v0.3.0
59    Build Set: lang/gcc491
60    config: devel/expat-2.1.0-1.cfg
61    package: expat-2.1.0-x86_64-apple-darwin13.2.0-1
62    building: expat-2.1.0-x86_64-apple-darwin13.2.0-1
63    config: devel/binutils-2.24-1.cfg
64    package: arm-eabihf-binutils-2.24-1
65    building: arm-eabihf-binutils-2.24-1
66    config: devel/gcc-4.9.1-newlib-2.1.0-1.cfg
67    package: arm-eabihf-gcc-4.9.1-newlib-2.1.0-1
68    building: arm-eabihf-gcc-4.9.1-newlib-2.1.0-1
69    config: devel/gdb-7.7-1.cfg
70    package: arm-eabihf-gdb-7.7-1
71    building: arm-eabihf-gdb-7.7-1
72    installing: expat-2.1.0-x86_64-apple-darwin13.2.0-1 -> /Users/chris/development/bare
73    installing: arm-eabihf-binutils-2.24-1 -> /Users/chris/development/bare
74    installing: arm-eabihf-gcc-4.9.1-newlib-2.1.0-1 -> /Users/chris/development/bare
75    installing: arm-eabihf-gdb-7.7-1 -> /Users/chris/development/bare
76    cleaning: expat-2.1.0-x86_64-apple-darwin13.2.0-1
77    cleaning: arm-eabihf-binutils-2.24-1
78    cleaning: arm-eabihf-gcc-4.9.1-newlib-2.1.0-1
79    cleaning: arm-eabihf-gdb-7.7-1
80
81RTEMS
[2674d6a]82^^^^^
[8b64335]83
84The RTEMS Configurations found in the ``rtems`` directory. The configurations
85are grouped by RTEMS version. In RTEMS the tools are specific to a specific
86version because of variations between Newlib and RTEMS. Restructuring in RTEMS
87and Newlib sometimes moves *libc* functionality between these two parts and
88this makes existing tools incompatible with RTEMS.
89
90RTEMS allows architectures to have different tool versions and patches. The
91large number of architectures RTEMS supports can make it difficult to get a
92common stable version of all the packages. An architecture may require a recent
93GCC because an existing bug has been fixed, however the more recent version may
94have a bug in other architecture. Architecture specific patches should be
95limited to the architecture it relates to. The patch may fix a problem on the
96effect architecture however it could introduce a problem in another
97architecture. Limit exposure limits any possible crosstalk between
98architectures.
99
100If you are building a released version of RTEMS the release RTEMS tar file will
101be downloaded and built as part of the build process. If you are building a
102tool set for use with the development branch of RTEMS, the development branch
103will be cloned directly from the RTEMS GIT repository and built.
104
105When building RTEMS within the RTEMS Source Builder it needs a suitable working
106``autoconf`` and ``automake``. These packages need to built and installed in their
107prefix in order for them to work. The RTEMS Source Builder installs all
108packages only after they have been built so if you host does not have a
109recent enough version of ``autoconf`` and ``automake`` you first need to build them
[2674d6a]110and install them then build your tool set. The commands are:
111
[d5b631f]112.. code-block:: none
[8b64335]113
114    $ ../source-builder/sb-set-builder --log=l-4.11-at.txt \
115       --prefix=$HOME/development/rtems/4.11 4.11/rtems-autotools
116    $ export PATH=~/development/rtems/4.11/bin:$PATH    <1>
117    $ ../source-builder/sb-set-builder --log=l-4.11-sparc.txt \
118       --prefix=$HOME/development/rtems/4.11 4.11/rtems-sparc
119
120.. topic:: Items:
121
122  1. Setting the path.
123
124If this is your first time building the tools and RTEMS it pays to add the
125``--dry-run`` option. This will run through all the configuration files and if
126any checks fail you will see this quickly rather than waiting for until the
127build fails a check.
128
129To build snapshots for testing purposes you use the available macro maps
130passing them on the command line using the ``--macros`` option. For RTEMS these
131are held in ``config/snapshots`` directory. The following builds *newlib* from
[2674d6a]132CVS:
133
[d5b631f]134.. code-block:: none
[8b64335]135
136    $ ../source-builder/sb-set-builder --log=l-4.11-sparc.txt \
137       --prefix=$HOME/development/rtems/4.11 \
138       --macros=snapshots/newlib-head.mc \
139       4.11/rtems-sparc
140
141and the following uses the version control heads for ``binutils``, ``gcc``,
[2674d6a]142``newlib``, ``gdb`` and *RTEMS*:
143
[d5b631f]144.. code-block:: none
[8b64335]145
146    $ ../source-builder/sb-set-builder --log=l-heads-sparc.txt \
147       --prefix=$HOME/development/rtems/4.11-head \
148       --macros=snapshots/binutils-gcc-newlib-gdb-head.mc \
149       4.11/rtems-sparc
150
[f95699b]151Following features can be enabled/disabled via the command line for the RTEMS
152build sets:
153
154``--without-rtems``
155  Do not build RTEMS when building an RTEMS build set.
156
157``--without-cxx``
158  Do not build a C++ compiler.
159
160``--with-ada``
161  Attempt to build an Ada compiler.  You need a native GNAT installed.
162
163``--with-fortran``
164  Attempt to build a Fortran compiler.
165
166``--with-objc``
167  Attempt to build a C++ compiler.
168
[8b64335]169Patches
[2674d6a]170^^^^^^^
[8b64335]171
172Packages being built by the RSB need patches from time to time and the RSB
173supports patching upstream packages. The patches are held in a seperate
174directory called ``patches`` relative to the configuration directory you are
175building. For example ``%{_topdir}/patches:%{_sbdir}/patches``. Patches are
176declared in the configuration files in a similar manner to the package's source
177so please refer to the ``%source`` documentation. Patches, like the source, are
178to be made publically available for configurations that live in the RSB package
179and are downloaded on demand.
180
181If a package has a patch management tool it is recommended you reference the
182package's patch management tools directly. If the RSB does not support the
183specific patch manage tool please contact the mailing list to see if support
184can be added.
185
186Patches for packages developed by the RTEMS project can be placed in the RTEMS
187Tools Git repository. The ``tools`` directory in the repository has various
188places a patch can live. The tree is broken down in RTEMS releases and then
189tools within that release. If the package is not specific to any release the
190patch can be added closer to the top under the package's name. Patches to fix
191specific tool related issues for a specific architecture should be grouped
192under the specific architecture and only applied when building that
193architecture avoiding a patch breaking an uneffected architecture.
194
195Patches in the RTEMS Tools repository need to be submitted to the upstream
196project. It should not be a clearing house for patches that will not be
197accepted upstream.
198
199Patches are added to a component's name and in the ``%prep:`` section the
200patches can be set up, meaning they are applied to source. The patches
201are applied in the order they are added. If there is a dependency make
202sure you order the patches correctly when you add them. You can add any
203number of patches and the RSB will handle them efficently.
204
205Patches can have options. These are added before the patch URL. If no options
206are provided the patch's setup default options are used.
207
208Patches can be declared in build set up files.
209
[2674d6a]210This examples shows how to declare a patch for gdb in the ``lm32`` architecture:
211
212.. code-block:: spec
[8b64335]213
214    %patch add <1> gdb <2> %{rtems_gdb_patches}/lm32/gdb-sim-lm32uart.diff <3>
215
216.. topic:: Items:
217
218  1. The patch's ``add`` command.
219
220  2. The group of patches this patch belongs too.
221
222  3. The patch's URL. It is downloaded from here.
223
224Patches require a checksum to avoid a warning. The ``%hash`` directive can be
[2674d6a]225used to add a checksum for a patch that is used to verify the patch:
226
227.. code-block:: spec
[8b64335]228
229    %hash md5 <1> gdb-sim-lm32uart.diff <2> 77d070878112783292461bd6e7db17fb <3>
230
231.. topic:: Items:
232
233  1. The type of checksum, in the case an MD5 hash.
234
235  2. The patch file the checksum is for.
236
237  3. The MD5 hash.
238
239The patches are applied when a patch ``setup`` command is issued in the
240``%prep:`` section. All patches in the group are applied. To apply the GDB
[2674d6a]241patch above use:
242
243.. code-block:: spec
[8b64335]244
245    %patch setup <1> gdb <2> -p1 <3>
246
247.. topic:: Items:
248
249  1. The patch's ``setup`` command.
250
251  2. The group of patches to apply.
252
253  3. The patch group's default options. If no option is given with the patch
254     these options are used.
255
256Architecture specific patches live in the architecture build set file isolating
257the patch to that specific architecture. If a patch is common to a tool it
258resides in the RTEMS tools configuration file. Do not place patches for tools
259in the ``source-builder/config`` template configuration files.
260
261To test a patch simply copy it to your local ``patches`` directory. The RSB
262will see the patch is present and will not attempt to download it. Once you are
263happy with the patch submit it to the project and a core developer will review
[3605600]264it and add it to the RTEMS Tools git repository.
265
266Testing a Newlib Patch
267~~~~~~~~~~~~~~~~~~~~~~
268
269To test a local patch for newlib, you need to add the following
270two lines to the ``.cfg`` file in ``rsb/rtems/config/tools/`` that is included
271by the bset you use:
272
273.. topic:: Steps:
274
275  1. Create patches for the changes you want to test. (Note: For RSB, before
276     creating Newlib patch, you must run ``autoreconf -fvi`` in the required
277     directory after you make changes to the code. This is not required when
278     you create patch to send to ``newlib-devel``. But if you want RSB to
279     address your changes, your patch should also include regenerated files.)
280
281  2. Calculate ``sha512`` of your patch.
282
283  3. Place the patches in ``rsb/rtems/patches`` directory.
284
285  4. Open the ``.bset`` file used by your BSP in ``rsb/rtems/config``.
286     For example, for ``rtems5``, ``SPARC``, the file will be
287     ``rsb/rtems/config/5/rtems-sparc.bset``.
288
289  5. Inside it you will find the name of ``.cfg`` file for Newlib, used by
290     your BSP.
291     For example, I found ``tools/rtems-gcc-7.4.0-newlib-1d35a003f``.
292
293  6. Edit your ``.cfg`` file. In my case it will be,
294     ``rsb/rtems/config/tools/rtems-gcc-7.4.0-newlib-1d35a003f.cfg``. And
295     add the information about your patch as mentioned below.
[8b64335]296
[2674d6a]297.. code-block:: spec
[8b64335]298
[3605600]299    %patch add newlib -p1 file://0001-Port-ndbm.patch <1>
300    %hash sha512 0001-Port-ndbm.patch 7d999ceeea4f3dc82e8e0aadc09d983a7a68b44470da8a3d61ab6fc558fdba6f2c2de3acc2f32c0b0b97fcc9ab799c27e87afe046544a69519881f947e7881d1 <2>
[8b64335]301
302.. topic:: Items:
303
304  1. The diff file prepended with ``file://`` to tell RSB this is a local file.
305
[3605600]306  2. The output from sha512sum on the patch file.
Note: See TracBrowser for help on using the repository browser.