summaryrefslogtreecommitdiffstats
path: root/user/bld/index.rst
blob: ebedf5a1f143d2c0ea22164c648a28464d6139b5 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
.. SPDX-License-Identifier: CC-BY-SA-4.0

.. Copyright (C) 2019, 2020 embedded brains GmbH
.. Copyright (C) 2019, 2020 Sebastian Huber

.. index:: BSP build system
.. index:: build system

.. _BSPBuildSystem:

BSP Build System
****************

The purpose of the build system is to produce and install artefacts from the
RTEMS sources such as static libraries, start files, linker command files,
configuration header files, header files, test programs, package description
files, and third-party build system support files for a specific BSP in a user
controlled configuration.

Overview
========

The build system consists of three components which are all included in the
RTEMS sources

* the `waf <https://waf.io/>`_ meta build system command line tool,

* a `wscript <https://git.rtems.org/rtems/tree/wcript>`_ file used by ``waf``,
  and

* a
  `set of build specification items <https://git.rtems.org/rtems/tree/spec/build>`_
  maintained by a text editor just like other source files.

The build system is controlled by the user through

* commands passed to the ``waf`` command line tool,

* command line options passed to ``waf``, and

* configuration files (e.g. ``config.ini``) used by ``wscript`` through ``waf``
  invocations.

Configurable things which are subject to a local installation variant such as
paths to tools are intended to be passed as command line options to the ``waf``
command line tool.  Which BSPs are built and how they are configured by means of
options is placed in configuration files (e.g. ``config.ini``).  The
configuration files may reside anywhere in the file system and the goal is to
have it under version control by the user.

Work Flow
=========

There are five steps necessary to build and install one or more BSPs.

1. Select which BSPs you want to build.  See also :ref:`BSPs` and
   ``./waf bsp_list``.

2. Write a BSP build configuration file (e.g. ``config.ini``) which determines
   which BSPs are built and how they are configured.

3. Run the ``./waf configure`` command to generate the build
   environment.

4. Build the BSP artefacts with ``./waf``.  The build uses the build environment
   created by ``./waf configure``.  The BSP build configuration file (e.g.
   ``config.ini``) is no longer used and may be deleted.

5. Install the BSP artefacts with ``./waf install``.

Commands
========

The build system is controlled by invocations of the ``./waf`` command line
tool instead of the well known ``make``.  Since waf is written in Python, a
standard Python 2.7 or 3 installation without third-party packages is required
to run it.  The ``./waf`` command line tool must be invoked in the RTEMS source
tree top-level directory.

Some commands accept the ``--rtems-specs`` command line option.  This option
specifies paths to build specification items.  It is an advanced option and
there is normally no need to use it.  It may be used to customize the build at
the level of the build specification.  For more information see the
`Build System` chapter of the
`RTEMS Software Engineering <https://docs.rtems.org/branches/master/eng/build-system.rst>`_
guide.

Help
----

Use ``./waf --help`` to get a list of commands and options.

BSP List
--------

The BSP list command ``./waf bsp_list`` loads the build specification items and
generates a list of base BSPs from it.  The list is sorted by architecture and
base BSP name.  Which base BSPs are listed can be controlled by the
``--rtems-bsps`` command line option.  It expects a comma-separated list of
`Python regular expressions <https://docs.python.org/3/library/re.html#regular-expression-syntax>`_
which select the desired BSP variants.  The path to the build specification
items can be specified by the ``--rtems-specs`` command line option.

.. code-block:: none

    $ ./waf bsp_list --rtems-bsps=sparc/
    sparc/at697f
    sparc/erc32
    sparc/gr712rc
    sparc/gr740
    sparc/leon2
    sparc/leon3
    sparc/ut699
    sparc/ut700

.. code-block:: none

    $ ./waf bsp_list --rtems-bsps='/leon,/rv64imac$'
    riscv/rv64imac
    sparc/leon2
    sparc/leon3

BSP Defaults
------------

The BSP defaults command ``./waf bsp_defaults`` loads the build specification
items and generates a list options with default values for each base BSP from
it.  The list is sorted by architecture and base BSP name.  Which base BSPs are
listed can be controlled by the ``--rtems-bsps`` command line option.  Default
values may depend on the selected compiler.  The compiler can be specified by
the ``--rtems-compiler`` command line option.  The path to the build
specification items can be specified by the ``--rtems-specs`` command line
option.

.. code-block:: none

    $ ./waf bsp_defaults --rtems-bsps=gr712rc --rtems-compiler=gcc | grep ABI_FLAGS
    ABI_FLAGS = -mcpu=leon3 -mfix-gr712rc

.. code-block:: none

    $ ./waf bsp_defaults --rtems-bsps=gr712rc --rtems-compiler=clang | grep ABI_FLAGS
    ABI_FLAGS = -mcpu=gr712rc

Configure
---------

The configure command ``./waf configure`` loads the BSP build configuration
files and the build specification items and configures the build environment
accordingly.  The configuration files can be specified by the ``--rtems-config``
command line option.  It expects a comma-separated list of paths to the
configuration files.  By default, the file ``config.ini`` is used.  The paths to
RTEMS tools can be specified by the ``--rtems-tools`` command line option.  It
expects a comma-separated list of prefix paths to tools, e.g.  compiler, linker,
etc.  By default, the installation prefix is used for the RTEMS tools.  Tools
are searched in the prefix path and also in a ``bin`` subdirectory of the prefix
path.  The path to the build specification items can be specified by the
``--rtems-specs`` command line option.

Build, Clean, and Install
-------------------------

The commands ``./waf``, ``./waf clean``, and ``./waf install`` load the build
specification items according to the specification paths stored in the build
environment.  The BSP build configuration files (e.g. ``config.ini``) used by
the ``./waf configure`` command to create the build environment are not longer
used and may be deleted.  The build commands perform a dependency tracking and
re-build artefacts if input sources changed.  Input sources are also the build
specification.

Configuration
=============

The BSP build configuration is done via INI-style configuration files.  The
configuration files are consumed by the ``./waf configure`` command.  By
default, the file ``config.ini`` is used.  You can specify other configuration
files with the ``--rtems-config`` command line option.  The configuration files
consist of sections and options (key-value pairs).

To build a particular BSP, you have to create a section with the BSP variant
name.

.. code-block:: ini

    [sparc/erc32]

This one line configuration file is sufficient to build the base BSP
`sparc/erc32` with default values for all options.  The base BSPs are determined
by the build specification.  The ``./waf bsp_list`` command lists all base BSPs.
You can create your own BSP names.  However, in this case you have to inherit
from a base BSP.  The inheritance works only within an architecture, e.g. a
`riscv` BSP cannot inherit options from an `arm` BSP.

.. code-block:: ini

    [sparc/foobar]
    INHERIT = erc32

The inheritance works recursively and must end up in a base BSP.

.. code-block:: ini

    [sparc/foo]
    INHERIT = erc32

    [sparc/bar]
    INHERIT = foo

A child BSP variant inherits all options from the parent BSP variant.  The child
BSP can override the inherited options.

You can determine the compiler used to build the BSP with the ``COMPILER``
option.

.. code-block:: ini

    [sparc/gr740_gcc]
    INHERIT = gr740
    COMPILER = gcc

    [sparc/gr740_clang]
    INHERIT = gr740
    COMPILER = clang

Use the ``./waf bsp_defaults`` command to get a list of all configuration
options with default values.

.. code-block:: none

    $ ./waf bsp_defaults --rtems-bsps=sparc/erc32
    [sparc/erc32]
    # Flags passed to the library archiver
    ARFLAGS = crD
    # Warning flags passed to the C compiler
    CC_WARNING_FLAGS = -Wmissing-prototypes -Wimplicit-function-declaration -Wstrict-prototypes -Wnested-externs
    # Warning flags passed to the C++ compiler
    CXX_WARNING_FLAGS =
    # Flags passed to the linker (GNU ld)
    LDFLAGS = -Wl,--gc-sections
    # Enable the Ada support
    __RTEMS_ADA__ = False
    # Enable the RTEMS internal debug support
    RTEMS_DEBUG = False
    ...
    # Install the legacy application Makefile framework.
    INSTALL_LEGACY_MAKEFILES = True

It is not recommended to blindly add all the options obtained through the
``./waf bsp_defaults`` command to custom configuration files.  The specified
options should be kept at the necessary minimum to get the desired build.

Some projects may still want to specify all options in a configuration file to
be independent of changes in the base BSP.  You can review differences between
the user and base BSP values with the ``diff`` command.

.. code-block:: none

    $ ./waf bsp_defaults --rtems-bsps=sparc/erc32 > config.ini
    $ sed -i 's/BUILD_TESTS = False/BUILD_TESTS = True/' config.ini
    $ ./waf bsp_defaults --rtems-bsps=sparc/erc32 | diff -u - config.ini
    --- config.ini  2019-12-04 08:21:36.049335872 +0100
    +++ -   2019-12-04 08:21:41.187432405 +0100
    @@ -31,7 +31,7 @@
     # Build the Ada test programs (may be also enabled by BUILD_TESTS)
     BUILD_ADATESTS = False
     # Build the test programs
    -BUILD_TESTS = False
    +BUILD_TESTS = True
     # Build the benchmark programs (may be also enabled by BUILD_TESTS)
     BUILD_BENCHMARKS = False
     # Build the file system test programs (may be also enabled by

There is a special section ``DEFAULT`` which can be used to specify default
values for all other sections of the configuration file.  In the following
example configuration file, building of the tests is enabled for the
`sparc/erc32` and the `riscv/griscv` BSP.

.. code-block:: ini

    [DEFAULT]
    BUILD_TESTS = True

    [sparc/erc32]

    [riscv/griscv]

Migration from Autoconf/Automake
================================

The Autoconf/Automake based build system used a ``configure`` command to
configure a single target architecture and one or more BSPs.  The ``make``
command was used to build it.  The ``configure`` command is replaced by a
``./waf configure`` invocation with configuration file.  The ``make`` command
is replaced by ``./waf`` and ``make install`` is replaced by ``./waf install``.

Here are some hints for how a configure command line can be converted to
options in the configuration file of the ``waf`` based build system.  BSP
options given at the configure command line have to be added to the BSP section
in the configuration file.

``--target=${arch}-rtems6`` ``--enable-rtembsp=${bsp}``
        To build a BSP add ``[${arch}/${bsp}]`` to the configuration file.

``--enable-ada`` | ``--disable-ada``
        Set ``__RTEMS_ADA__`` to ``True`` or ``False`` in the BSP section of
        the configuration file.

``--enable-multiprocessing`` | ``--disable-multiprocessing``
        Set ``RTEMS_MULTIPROCESSING`` to ``True`` or ``False`` in the BSP
        section of the configuration file.

``--enable-networking`` | ``--disable-networking``
        Set ``RTEMS_NETWORKING`` to ``True`` or ``False`` in the BSP section of
        the configuration file.

``--enable-paravirt`` | ``--disable-paravirt``
        Set ``RTEMS_PARAVIRT`` to ``True`` or ``False`` in the BSP section of
        the configuration file.

``--enable-profiling`` | ``--disable-profiling``
        Set ``RTEMS_PROFILING`` to ``True`` or ``False`` in the BSP section of
        the configuration file.

``--enable-posix`` | ``--disable-posix``
        Set ``RTEMS_POSIX_API`` to ``True`` or ``False`` in the BSP section of
        the configuration file.

``--enable-rtems-debug`` | ``--disable-rtems-debug``
        Set ``RTEMS_DEBUG`` to ``True`` or ``False`` in the BSP section of the
        configuration file.

``--enable-smp`` | ``--disable-smp``
        Set ``RTEMS_SMP`` to ``True`` or ``False`` in the BSP section of the
        configuration file.

``--enable-tests`` | ``--disable-tests``
        Set ``BUILD_TESTS`` to ``True`` or ``False`` in the BSP section of the
        configuration file.

``--enable-tests=samples``
        Set ``BUILD_SAMPLES`` to ``True`` or ``False`` in the BSP section of
        the configuration file.

Please have a look at the following example configuration file.

.. code-block:: ini

    # --target=sparc-rtems6 --enable-rtemsbsp=erc32
    [sparc/erc32]

    # --enable-ada
    __RTEMS_ADA__ = True

    # --enable-multiprocessing
    RTEMS_MULTIPROCESSING = False

    # --enable-networking
    RTEMS_NETWORKING = True

    # --disable-paravirt
    RTEMS_PARAVIRT = False

    # --enable-profiling
    RTEMS_PROFILING = True

    # --disable-posix
    RTEMS_POSIX_API = False

    # --enable-rtems-debug
    RTEMS_DEBUG = True

    # --disable-smp
    RTEMS_SMP = False

    # --enable-tests
    BUILD_TESTS = True

    # BSP_POWER_DOWN_AT_FATAL_HALT=
    BSP_POWER_DOWN_AT_FATAL_HALT = False