[PATCH] eng: Add build system chapter
Sebastian Huber
sebastian.huber at embedded-brains.de
Fri Nov 8 13:56:38 UTC 2019
Update #3818.
---
This is the first draft of the documentation of the new build system from the
RTEMS maintainer perspective.
I work the documentation for the user manual next week. The next step is to
convert all tests to the new build system (except Ada tests). The final step is
to convert all BSPs.
I removed the binary files from the patch. For the generated document see:
https://ftp.rtems.org/pub/rtems/people/sebh/eng.pdf
You can find a prototype implementation of the new build system here:
https://git.rtems.org/sebh/rtems.git/commit/?h=build
I do forced pushes to this branch.
You can test it with:
git clone git://git.rtems.org/sebh/rtems.git
cd rtems
git checkout --track origin/build
./waf bsp_defaults --rtems-bsps=sparc > bsps.ini
./waf configure
./waf
To build all supported BSPs, you can do:
./waf bsp_list | sed 's/\(.*\)/[\1]/' > all.ini
./waf configure --rtems-options=all.ini
./waf
eng/build-system.rst | 1032 ++++++++++++++++++++++++++++++++++++++++++++
eng/index.rst | 1 +
images/eng/build-deps.dot | 58 +++
images/eng/build-deps.pdf | Bin 0 -> 18641 bytes
images/eng/build-deps.png | Bin 0 -> 18098 bytes
images/eng/build-deps2.dot | 47 ++
images/eng/build-deps2.pdf | Bin 0 -> 17661 bytes
images/eng/build-deps2.png | Bin 0 -> 28188 bytes
8 files changed, 1138 insertions(+)
create mode 100644 eng/build-system.rst
create mode 100644 images/eng/build-deps.dot
create mode 100644 images/eng/build-deps.pdf
create mode 100644 images/eng/build-deps.png
create mode 100644 images/eng/build-deps2.dot
create mode 100644 images/eng/build-deps2.pdf
create mode 100644 images/eng/build-deps2.png
diff --git a/eng/build-system.rst b/eng/build-system.rst
new file mode 100644
index 0000000..3a5daaf
--- /dev/null
+++ b/eng/build-system.rst
@@ -0,0 +1,1032 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2019 embedded brains GmbH
+
+.. _BuildSystem:
+
+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.
+
+Goals
+=====
+
+The build system should meet the following goals:
+
+* Easy build configuration of BSPs through configuration options
+
+* Enable the BSP build configuration to be placed in a version control system
+ (e.g. no local paths)
+
+* Fast builds (also on Windows)
+
+* Easy to maintain, e.g. add/remove a BSP, add/change/remove configuration
+ options, add/remove a library, add/remove an object to/from a library,
+ add/remove tests
+
+* Reusable build specifications (e.g. generate documentation for BSP options for
+ the user manual)
+
+* Validation of built artefacts (e.g. ensure that the objects are built as
+ specified using the DWARF debug information)
+
+* Support building of BSPs external to the project
+
+* Customization of the build (e.g. build only a subset of the RTEMS functions)
+
+* Support alternative compilers such as clang instead of GCC
+
+* Ability to unit test the build system
+
+Overview
+========
+
+The build system consists of three components
+
+* 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 maintained by
+ :ref:`Doorstop <RegEngDoorstop>`.
+
+The build system is controlled by the user through
+
+* commands passed to the ``waf`` command line tool,
+
+* options passed to ``waf``, and
+
+* configuration files 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 options to the ``waf`` command line
+tool. Configurable things which define what is built and how the artefacts are
+produced are intended to be placed in configuration files. The ``wscript`` file
+should know nothing about the layout of the sources. What is built and how it
+is built should be completely defined by the user configuration and the build
+specification items.
+
+Commands
+========
+
+BSP List
+--------
+
+The BSP list command ``waf bsp_list`` loads the build specification items and
+generates a list of base BSP variants from it. The list is sorted by
+architecture and base BSP variant name. The path to the build specification
+items can be specified by the ``--rtems-specs`` command line option. Which base
+BSP variants are listed can be controlled by the ``--rtems-bsps`` command line
+option.
+
+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 variant
+from it. The list is sorted by architecture and BSP base variant name. The
+path to the build specification items can be specified by the ``--rtems-specs``
+command line option. Which base BSP variants 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. Build specification items contribute to the command
+through the ``do_defaults()`` method in the ``wscript``.
+
+Configure
+---------
+
+The configure command ``waf configure`` loads the configuration files and the
+build specification items and configures the build environment accordingly. The
+configuration files can be specified by the ``--rtems-options`` command line
+option. The path to the build specification items can be specified by the
+``--rtems-specs`` command line option. The paths to tools can be specified by
+the ``--rtems-tools`` command line option. Build specification items contribute
+to the command through the ``prepare_configure()`` and ``do_configure()``
+methods in the ``wscript``.
+
+Build, Clean, and Install
+-------------------------
+
+The commands ``waf build``, ``waf clean``, and ``waf install`` load the build
+specification items according to the specification paths stored in the build
+environment.
+Build specification items contribute to the commands through the
+``prepare_build()`` and ``do_build()`` methods in the ``wscript``.
+
+Build Specification Items
+=========================
+
+The build specification items are used by the ``wscript`` to determine what it
+should do. The entry point to what is built are the BSP items and the top-level
+group items. The user configuration defines which BSPs are built. The
+top-level groups are defined by the set of specification items available through
+the specification paths given to the ``waf configure`` command.
+
+All items have the standard attributes of the :ref:`ReqEngSpecItems`. All
+attributes specified are mandatory and shall be present in the item files. The
+``wscript`` does not provide default values. The ``type`` value shall be
+``build``. All build specification items items shall have the following item
+attributes:
+
+build-type
+ The `build-type` value shall be one of the values specified below.
+
+order
+ The `order` value shall be an integer. It specifies the order in which
+ linked items are processed. Items are ordered according to the integers,
+ e.g. -13 precedes 42. Use 0 by default.
+
+ The `order` attribute is a trade-off between the specification complexity
+ and a strict dependency definition. Dependencies are normally explicit
+ though the item links. However, using only explicit dependencies would make
+ the specification quite complex, see :ref:`BuildExplicitDeps`.
+
+ .. _BuildExplicitDeps:
+
+ .. figure:: ../images/eng/build-deps.*
+ :width: 100%
+ :figclass: align-center
+
+ Example for Explicit Build Item Dependencies
+
+ In the example with the explicit build system dependencies a user wants to
+ build a group of tests. Each test program has a dependency on the standard
+ RTEMS libraries. The first issue is that the ``librtemsbsp.a`` needs
+ dependencies to all BSPs. The dependencies are the values of the ``links``
+ attribute in the library item files. External BSPs would have to modify the
+ library item file. This is quite undesirable. The second issue is that the
+ source files of the ``librtemscpu.a`` need a dependency to the ABI compiler
+ flags specified by each BSP. The third issue is that each BSP has to define
+ its own ``bspopts.h`` configuration header item. These issues are avoided
+ through the ``order`` attribute and explicit `BSP Items`. It helps to order
+ the build globally.
+
+ .. _BuildOrderDeps:
+
+ .. figure:: ../images/eng/build-deps2.*
+ :width: 40%
+ :figclass: align-center
+
+ Example for Build Item Dependencies via Order Attribute and BSP Items
+
+ In the :ref:`BuildOrderDeps`, the BSP is configured and built before all
+ other items. The top-level test group is ordered so that it is configured
+ and built after the libraries top-level group.
+
+Frequently Used Attributes
+--------------------------
+
+The following item attributes are used by several build specification items:
+
+.. _BuildAttrCflags:
+
+cflags
+ The `cflags` value shall be a list of options for the C compiler. They are
+ used to compile the sources of this item. They succeed the options
+ presented to the item by the build item context.
+
+.. _BuildAttrCppflags:
+
+cppflags
+ The `cppflags` value shall be a list of options for the C preprocessor.
+ They are used to pre-process the sources of this item. They succeed the
+ options presented to the item by the build item context.
+
+.. _BuildAttrCxxflags:
+
+cxxflags
+ The `cxxflags` value shall be a list of options for the C++ compiler. They
+ are used to compile the sources of this item. They succeed the options
+ presented to the item by the build item context.
+
+.. _BuildAttrDestination:
+
+destination
+ The `destination` value shall be the installation path of target file.
+
+.. _BuildAttrIncludes:
+
+includes
+ The `includes` value shall be a list of paths to header files. The paths
+ are used by the C preprocessor to search for header files. They succeed the
+ includes presented to the item by the build item context. For
+ :ref:`BuildGroupItems` the includes are visible to all items referenced by
+ the group item. For :ref:`BuildBSPItems`, :ref:`BuildObjectsItems`,
+ :ref:`BuildLibraryItems`, :ref:`BuildStartFileItems`, and
+ :ref:`BuildTestProgramItems` the includes are only visible to the sources
+ specified by the item itself and they do not propagate to referenced items.
+
+.. _BuildAttrInstall:
+
+install
+ The `install` value shall a list of dictionaries with `destination` and
+ `source` key-value pairs. The `destination` value shall be the install
+ destination directory. The `source` value shall be a list of source files.
+ The path to a source file shall be relative to the directory of the
+ ``wscript``.
+
+.. _BuildAttrSource:
+
+source
+ The `source` value shall be a list of source files. The path to a source
+ file shall be relative to the directory of the ``wscript``.
+
+.. _BuildAttrTarget:
+
+target
+ The `target` value shall be the target file path. The path to the target
+ file shall be relative to the directory of the ``wscript``. The target file
+ is located in the build tree.
+
+.. _BuildBSPItems:
+
+BSP Items
+---------
+
+The ``build-type`` value shall be ``bsp``. The specialized item attributes are:
+
+arch
+ The `arch` value shall be the target architecture.
+
+bsp
+ The `bsp` value shall be the base BSP variant name.
+
+cflags
+ See :ref:`cflags <BuildAttrCflags>`.
+
+cppflags
+ See :ref:`cppflags <BuildAttrCppflags>`.
+
+includes
+ See :ref:`includes <BuildAttrIncludes>`.
+
+source
+ See :ref:`source <BuildAttrSource>`.
+
+install
+ See :ref:`install <BuildAttrInstall>`.
+
+family
+ The `family` value shall be the the BSP family name. The name shall be the
+ last directory of the path to the BSP sources.
+
+Example:
+
+.. code-block:: yaml
+
+ active: true
+ arch: sparc
+ bsp: erc32
+ build-type: bsp
+ cflags: []
+ cppflags: []
+ derived: true
+ enabled-by: []
+ family: erc32
+ header: ''
+ includes: []
+ install:
+ - destination: ${BSP_INCLUDEDIR}
+ source:
+ - bsps/sparc/erc32/include/erc32.h
+ - bsps/sparc/erc32/include/bsp.h
+ - bsps/sparc/erc32/include/tm27.h
+ - destination: ${BSP_INCLUDEDIR}/bsp
+ source:
+ - bsps/sparc/erc32/include/bsp/irq.h
+ level: 1.0
+ links:
+ - RTEMS-BUILD-BSP-BSPOPTS: kt3y7ie7HP9LhKOwwJHME-1n--DeeNNpZjFYBq_GT_w=
+ - RTEMS-BUILD-BSP-IRQOBJS: 53VttLhTsBrxeLpydfi44cyYSWsaXSQnID7kBjHVVvA=
+ - RTEMS-BUILD-BSP-O2: RRJhqKUzEPxgCMGswDNVM5d6muMZd8OH_JHEVNMWv1k=
+ - RTEMS-BUILD-BSP-OBJS: G3nZiEJdrxpN0oqcuDq8o0pt756DYfMk2UECU6ULObA=
+ - RTEMS-BUILD-BSP-SPARC-START: vs5yXA5jsmGfCK_ILflnbvKbUh_0xjaPaioC1thByCM=
+ - RTEMS-BUILD-BSP-SPARC-ERC32-ABI: I2RtTMi4-I_ZFznOGYAMFpdPzucAr3x5-DOBaO6Qf_I=
+ - RTEMS-BUILD-BSP-SPARC-ERC32-SMPOBJS: 9m4rIQsBOJiXdQ-xHCJQNuJ0Ubbebb15CFrxjZRU_jI=
+ normative: true
+ order: 0
+ ref: ''
+ reviewed: _xNSgYjb5W_2BNKQCdeQ4MhyiP-TO7OEmAagS3or0UA=
+ source:
+ - bsps/shared/cache/nocache.c
+ - bsps/shared/dev/getentropy/getentropy-cpucounter.c
+ - bsps/shared/dev/serial/legacy-console.c
+ - bsps/shared/dev/serial/legacy-console-control.c
+ - bsps/shared/dev/serial/legacy-console-select.c
+ - bsps/shared/irq/irq-default-handler.c
+ - bsps/shared/start/bspfatal-default.c
+ - bsps/shared/start/bspreset-empty.c
+ - bsps/shared/start/sbrk.c
+ - bsps/sparc/erc32/btimer/btimer.c
+ - bsps/sparc/erc32/clock/ckinit.c
+ - bsps/sparc/erc32/console/debugputs.c
+ - bsps/sparc/erc32/console/erc32_console.c
+ - bsps/sparc/erc32/gnatsupp/gnatsupp.c
+ - bsps/sparc/erc32/start/boardinit.S
+ - bsps/sparc/erc32/start/bspdelay.c
+ - bsps/sparc/erc32/start/bspidle.c
+ - bsps/sparc/erc32/start/bspstart.c
+ - bsps/sparc/erc32/start/erc32mec.c
+ - bsps/sparc/erc32/start/setvec.c
+ - bsps/sparc/erc32/start/spurious.c
+ - bsps/sparc/shared/gnatcommon.c
+ - bsps/sparc/shared/irq/bsp_isr_handler.c
+ - bsps/sparc/shared/irq/irq-shared.c
+ - bsps/sparc/shared/start/bsp_fatal_exit.c
+ - bsps/sparc/shared/start/bsp_fatal_halt.c
+ - bsps/sparc/shared/start/bspgetworkarea.c
+ text: ''
+ type: build
+
+.. _BuildConfigFileItems:
+
+Configuration File Items
+------------------------
+
+The ``build-type`` value shall be ``config-file``. The specialized item
+attributes are:
+
+destination
+ See :ref:`destination <BuildAttrDestination>`.
+
+content
+ The `content` value shall be the content of the configuration file. A
+ ``${VARIABLE}`` substitution is performed during the configure command
+ execution using the variables of the configuration set. Use ``$$`` for a
+ plain ``$`` character. To have all variables from sibling items available
+ for substitution it is recommended to set an ``order`` value greater than
+ zero for configuration files.
+
+target
+ See :ref:`target <BuildAttrTarget>`.
+
+Example:
+
+.. code-block:: yaml
+
+ active: true
+ build-type: config-file
+ content: |
+ MEMORY {
+ RAM : ORIGIN = ${RISCV_RAM_REGION_BEGIN}, LENGTH = ${RISCV_RAM_REGION_SIZE}
+ }
+
+ REGION_ALIAS ("REGION_START", RAM);
+ REGION_ALIAS ("REGION_TEXT", RAM);
+ REGION_ALIAS ("REGION_TEXT_LOAD", RAM);
+ REGION_ALIAS ("REGION_FAST_TEXT", RAM);
+ REGION_ALIAS ("REGION_FAST_TEXT_LOAD", RAM);
+ REGION_ALIAS ("REGION_RODATA", RAM);
+ REGION_ALIAS ("REGION_RODATA_LOAD", RAM);
+ REGION_ALIAS ("REGION_DATA", RAM);
+ REGION_ALIAS ("REGION_DATA_LOAD", RAM);
+ REGION_ALIAS ("REGION_FAST_DATA", RAM);
+ REGION_ALIAS ("REGION_FAST_DATA_LOAD", RAM);
+ REGION_ALIAS ("REGION_RTEMSSTACK", RAM);
+ REGION_ALIAS ("REGION_WORK", RAM);
+
+ INCLUDE linkcmds.base
+ derived: false
+ destination: ${BSP_LIBDIR}/linkcmds
+ enabled-by: []
+ header: ''
+ level: 1.3
+ links: []
+ normative: true
+ order: 1000
+ ref: ''
+ reviewed: E3oxPkiXxl6OF-CbAPybZ3Uj-yDa-gX0TNlCe8KI_AE=
+ target: linkcmds
+ text: ''
+ type: build
+
+.. _BuildConfigHeaderItems:
+
+Configuration Header Items
+--------------------------
+
+The ``build-type`` value shall be ``config-header``. All collected
+configuration defines are written to the configuration header file during the
+configure command execution. To have all configuration defines from sibling
+items available it is recommended to set an ``order`` value greater than zero
+for configuration header files. The specialized item attributes are:
+
+destination
+ See :ref:`destination <BuildAttrDestination>`.
+
+include-headers:
+ The `include-headers` value shall be a list of header files to include via
+ ``#include <...>``.
+
+target
+ See :ref:`target <BuildAttrTarget>`.
+
+Example:
+
+.. code-block:: yaml
+
+ active: true
+ build-type: config-header
+ derived: false
+ destination: ${BSP_INCLUDEDIR}/bspopts.h
+ enabled-by: []
+ guard: __BSP_OPTIONS_H
+ header: ''
+ include-headers: []
+ level: '1.30'
+ links:
+ - RTEMS-BUILD-BSP-ABIFLAGS: 9S6xLt9NNTeh7TML05T2jYdN5pVs4S6Z-e3mWIjWpCw=
+ - RTEMS-BUILD-BSP-ASFLAGS: zM8gZZU1KdeHQaDmbPFVsj98H8ifK0mRv-m-mwENuKI=
+ - RTEMS-BUILD-BSP-INCLUDES: SU7veJS8vcm3y9MNLrCwR-4j6P8zaxbfIAc-o9-O5V0=
+ - RTEMS-BUILD-BSP-LDFLAGS: 6HoMy5B4IKqMs0mRkW5MDzKj2q-bgAXy-GmxAo2kDuI=
+ - RTEMS-BUILD-BSP-RTEMSBSP: em1kA2j4NfhyEX55AE4X0bvGmnTF0RQ42Fj5wfgiofw=
+ normative: true
+ order: 1000
+ ref: ''
+ reviewed: 3Safl89PDUi2mbLaEItgj5NQI1zcoPmB_kZHTVOPO44=
+ target: bsps/include/bspopts.h
+ text: ''
+ type: build
+
+.. _BuildGroupItems:
+
+Group Items
+-----------
+
+The ``build-type`` value shall be ``group``. The specialized item attributes
+are:
+
+top-level
+ The `top-level` value shall be a boolean value which indicates if this item
+ is a top-level group. Top-level groups are processed by the ``wscript``
+ after the BSP item. All other items are processed indirectly through the
+ item links.
+
+includes
+ See :ref:`includes <BuildAttrIncludes>`.
+
+ldflags
+ The `ldflags` value shall be a list of options for the linker. They are
+ used to link programs referenced by this item.
+
+use
+ The `use` value shall be a list of internal static libraries. They are used
+ to link programs referenced by this item, e.g. ``z`` for ``libz.a``.
+
+Example:
+
+.. code-block:: yaml
+
+ active: true
+ build-type: group
+ derived: false
+ enabled-by:
+ - BUILD_SAMPLES
+ header: ''
+ includes:
+ - testsuites/support/include
+ ldflags:
+ - -Wl,--wrap=printf
+ - -Wl,--wrap=puts
+ level: 1.82
+ links:
+ - RTEMS-BUILD-TEST-SAMPLE-BASEMPNODE1: Tlpq2qZQShWvKxI_OSal7uAN8ySE_Yfse39Aiu70BwI=
+ - RTEMS-BUILD-TEST-SAMPLE-BASEMPNODE2: i6vvggPdbcbc80d9CWVMH_hOaTT0w0KDe9spZ87E7q4=
+ - RTEMS-BUILD-TEST-SAMPLE-BASESP: lihIUBEc3n-Xg3F7RruYHzEdUlEdH0eJTOY9Yx_hduU=
+ - RTEMS-BUILD-TEST-SAMPLE-CAPTURE: bTQje3eByvPQfeN6P2g_-iJU-oTUxPjxWtFNROKsMZI=
+ - RTEMS-BUILD-TEST-SAMPLE-CDTEST: Rz284-Qef4aCkGrlBo8OlYzkIfuI15pLvokfz9Nwh7U=
+ - RTEMS-BUILD-TEST-SAMPLE-FILEIO: yZth0KUNtyoPy_Jr-64rfep-AoveSnZsRTp0BDGYB0I=
+ - RTEMS-BUILD-TEST-SAMPLE-HELLO: JgJ5wRtb6I5V2oEy1P4y_Jxdta_V-2IA-RMUcFGFfT4=
+ - RTEMS-BUILD-TEST-SAMPLE-IOSTREAM: L760VsZ8UwpdUIanl4emZjcKpm-vWOrJUkrLcG8ZIcg=
+ - RTEMS-BUILD-TEST-SAMPLE-LOOPBACK: teA8h0D24SuYvo_EzUxssflm4oDrV4XEgruUpPuqq2w=
+ - RTEMS-BUILD-TEST-SAMPLE-MINIMUM: f52VXG71KNwP71oemSxyTLJqKq6-6Q6ixo1Z9HDnNxo=
+ - RTEMS-BUILD-TEST-SAMPLE-NSECS: sWrSEIiSgZXsFuo0ddVEj02VMYImGOoFYH2vn6H9A1g=
+ - RTEMS-BUILD-TEST-SAMPLE-PARANOIA: G1-hdrPUiFLYBwyf_XTUMenZeMb2S-TsuSp2bMn4NV0=
+ - RTEMS-BUILD-TEST-SAMPLE-PPPD: WXeMKn-C8EYpWAH3WA3wy3YQA8PjkbhMYXfLkHzMdOY=
+ - RTEMS-BUILD-TEST-SAMPLE-TICKER: -GEWOVo01puXkp-o3dhk_mIBnBtD9Cl5TKAixNaD3GE=
+ - RTEMS-BUILD-TEST-SAMPLE-UNLIMITED: u91gEPu0j-SoedZGjXs4FzyDACgyrZXfgjBFmleO-9M=
+ normative: true
+ order: 0
+ ref: ''
+ reviewed: gxeEt12ZxZH6PETAqzTA2NnZelquSNCfk4b9dY2L-1o=
+ text: ''
+ top-level: false
+ type: build
+ use:
+ - rtemstest
+
+.. _BuildLibraryItems:
+
+Library Items
+-------------
+
+The ``build-type`` value shall be ``library``. Library items may use additional
+objects provided by :ref:`BuildObjectsItems`. The specialized item attributes
+are:
+
+cflags
+ See :ref:`cflags <BuildAttrCflags>`.
+
+cppflags
+ See :ref:`cppflags <BuildAttrCppflags>`.
+
+cxxflags
+ See :ref:`cxxflags <BuildAttrCxxflags>`.
+
+includes
+ See :ref:`includes <BuildAttrIncludes>`.
+
+install
+ See :ref:`install <BuildAttrInstall>`.
+
+install-path
+ The `install-path` value shall be the installation path of the library.
+
+source
+ See :ref:`source <BuildAttrSource>`.
+
+target
+ The `target` value shall be the name of the library, e.g. ``z`` for
+ ``libz.a``.
+
+Example:
+
+.. code-block:: yaml
+
+ active: true
+ build-type: library
+ cflags: []
+ cppflags: []
+ cxxflags: []
+ derived: false
+ enabled-by: []
+ header: ''
+ includes: []
+ install:
+ - destination: ${BSP_INCLUDEDIR}
+ source:
+ - cpukit/include/zconf.h
+ - cpukit/include/zlib.h
+ install-path: ${BSP_LIBDIR}
+ level: 1.14
+ links: []
+ normative: true
+ order: 0
+ ref: ''
+ reviewed: fCmWaj3nLWf12cOwqXVNJ-S2NrdgsHo7Jy9KoP_QFJA=
+ source:
+ - cpukit/zlib/adler32.c
+ - cpukit/zlib/compress.c
+ - cpukit/zlib/crc32.c
+ - cpukit/zlib/deflate.c
+ - cpukit/zlib/gzclose.c
+ - cpukit/zlib/gzlib.c
+ - cpukit/zlib/gzread.c
+ - cpukit/zlib/gzwrite.c
+ - cpukit/zlib/infback.c
+ - cpukit/zlib/inffast.c
+ - cpukit/zlib/inflate.c
+ - cpukit/zlib/inftrees.c
+ - cpukit/zlib/trees.c
+ - cpukit/zlib/uncompr.c
+ - cpukit/zlib/zutil.c
+ target: z
+ text: ''
+ type: build
+
+.. _BuildObjectsItems:
+
+Objects Items
+-------------
+
+The ``build-type`` value shall be ``objects``. The specialized item attributes
+are:
+
+cflags
+ See :ref:`cflags <BuildAttrCflags>`.
+
+cppflags
+ See :ref:`cppflags <BuildAttrCppflags>`.
+
+cxxflags
+ See :ref:`cxxflags <BuildAttrCxxflags>`.
+
+includes
+ See :ref:`includes <BuildAttrIncludes>`.
+
+install
+ See :ref:`install <BuildAttrInstall>`.
+
+source
+ See :ref:`source <BuildAttrSource>`.
+
+Example:
+
+.. code-block:: yaml
+
+ active: true
+ build-type: objects
+ cflags: []
+ cppflags: []
+ cxxflags: []
+ derived: false
+ enabled-by:
+ - RTEMS_SMP
+ header: ''
+ includes: []
+ install: []
+ level: 1.79
+ links: []
+ normative: true
+ order: 0
+ ref: ''
+ reviewed: d5jwFoggXfs3-55FTkkH73ojg1mvGPUz2WuNizd1234=
+ source:
+ - cpukit/score/src/percpustatewait.c
+ - cpukit/score/src/profilingsmplock.c
+ - cpukit/score/src/schedulerdefaultaskforhelp.c
+ - cpukit/score/src/schedulerdefaultpinunpin.c
+ - cpukit/score/src/schedulerdefaultsetaffinity.c
+ - cpukit/score/src/scheduleredfsmp.c
+ - cpukit/score/src/schedulerpriorityaffinitysmp.c
+ - cpukit/score/src/schedulerprioritysmp.c
+ - cpukit/score/src/schedulersimplesmp.c
+ - cpukit/score/src/schedulersmp.c
+ - cpukit/score/src/schedulersmpstartidle.c
+ - cpukit/score/src/schedulerstrongapa.c
+ - cpukit/score/src/smp.c
+ - cpukit/score/src/smplock.c
+ - cpukit/score/src/smpmulticastaction.c
+ - cpukit/score/src/smpunicastaction.c
+ - cpukit/score/src/threadunpin.c
+ text: ''
+ type: build
+
+.. _BuildOptionItems:
+
+Option Items
+------------
+
+The ``build-type`` value shall be ``option``. The specialized item attributes
+are:
+
+actions
+ The `actions` value shall a list of action dictionaries. Each action
+ operates on the value handed over by a previous action and the specified
+ arguments. The actions pass the processed option value to the next action
+ in the list. The first action starts with a value of ``None``. The actions
+ are carried out during the configure command execution. Each action
+ dictionary shall have exactly one of the following keys with action-specific
+ arguments:
+
+ assert-aligned
+ Expects exactly one argument. Asserts that the value is aligned
+ according to the argument.
+
+ assert-in-interval
+ Expects exactly two arguments. Asserts that the value is greater than
+ or equal to the first argument and less than or equal to the second
+ argument.
+
+ assert-int8 | assert-int16 | assert-int32 | assert-int64 | assert-uint8 | assert-uint16 | assert-uint32 | assert-uint64
+ Expects no argument. Asserts that the value is in the range of the
+ corresponding integer type.
+
+ assert-power-of-two
+ Expects no argument. Asserts that the value is a power of two.
+
+ check-cc | check-cxx
+ Expects a dictionary with ``cflags`` or ``cxxflags``, ``fragment``, and
+ ``message`` keys as argument. The ``cflags`` value shall be a list of
+ options for the C or C++ compiler. The ``fragment`` value shall be a
+ code fragment used to check the availability of a certain feature
+ through compilation with the C or C++ compiler. The resulting object is
+ not linked to an executable. The ``message`` value shall be a
+ description of the feature to check.
+
+ define-condition
+ Expects an optional argument. Adds a conditional define to the
+ configuration set. If the argument is present, then it is used as the
+ name of the define, otherwise the ``name`` of the item is used. The
+ value of the define is the value of the action.
+
+ define
+ Expects an optional argument. Adds a define to the configuration set.
+ If the argument is present, then it is used as the name of the define,
+ otherwise the ``name`` of the item is used. The value of the define is
+ the value of the action. If the value is a string, then it is quoted.
+
+ define-unquoted
+ Expects an optional argument. Adds a define to the configuration set.
+ If the argument is present, then it is used as the name of the define,
+ otherwise the ``name`` of the item is used. The value of the define is
+ the value of the action. If the value is a string, then it is not
+ quoted.
+
+ env-append
+ Expects an optional argument. Appends the value of the action to an
+ environment of the configuration set. If the argument is present, then
+ it is used as the name of the environment variable, otherwise the
+ ``name`` of the item is used.
+
+ env-assign
+ Expects an optional argument. Assigns the value of the action to an
+ environment of the configuration set. If the argument is present, then
+ it is used as the name of the environment variable, otherwise the
+ ``name`` of the item is used.
+
+ env-enable
+ Expects an optional argument. If the value of the action is true, then
+ a name is appended to the ``ENABLE`` environment variable of the
+ configuration set. If the argument is present, then it is used as the
+ name, otherwise the ``name`` of the item is used.
+
+ find-program
+ Tries to find the program specified by the value of the action. Returns
+ the result of the find operation, e.g. a path to the program.
+
+ format-and-define
+ Expects an optional argument. Adds a define to the configuration set.
+ If the argument is present, then it is used as the name of the define,
+ otherwise the ``name`` of the item is used. The value of the define is
+ the value of the action. The value is formatted according to the
+ ``format`` attribute value.
+
+ get-boolean | get-integer | get-string
+ Gets the value for subsequent actions from the configuration file though
+ the item ``name`` or uses the default value of the item. The value is
+ converted to a boolean, integer, or string.
+
+ get-env
+ Expects exactly one argument. Gets the value for subsequent actions
+ from the environment variable named by the argument of the configuration
+ set.
+
+ load
+ Loads the value to the configuration set.
+
+ script
+ Expects exactly one argument. Executes the argument with the Python
+ ``eval()`` function in the context of the script action handler.
+
+ set-value
+ Expects exactly one argument. Sets the value for subsequent actions to
+ the argument.
+
+ split
+ Expects no argument. Splits the value.
+
+ substitute
+ Expects no argument. Performs a ``${VARIABLE}`` substitution on the
+ value. Use ``$$`` for a plain ``$`` character.
+
+default
+ The `default` value shall be the default value of the option if no
+ variant-specific default value is specified. Use ``null`` to specify that
+ no default value exits. The variant-specific default values may be
+ specified by the ``default-by-variant`` attribute.
+
+default-by-variant
+ The `default-by-variant` value shall a list of dictionaries with `variant`
+ and `value` key-value pairs. The `variant` value shall be a Python regular
+ expression matching the desired variants. The `value` value shall be the
+ default value for the matching variants. The list is processed from top to
+ bottom. If a matching variant is found, then the processing stops.
+
+name
+ The `name` value shall be the name of the option.
+
+format
+ The `format` value shall be a
+ `Python format string <https://docs.python.org/3/library/string.html#formatstrings>`_.
+
+Example:
+
+.. code-block:: yaml
+
+ actions:
+ - get-boolean: null
+ - define-condition: null
+ active: true
+ build-type: option
+ default: false
+ default-by-variant:
+ - value: true
+ variant: qemu
+ derived: false
+ enabled-by: []
+ header: ''
+ level: 1.8
+ links: []
+ name: CLOCK_DRIVER_USE_FAST_IDLE
+ normative: true
+ order: 0
+ ref: ''
+ reviewed: pNr70QBReUMOjpRo9FMAKnGIjUb8XX2LBYtMhSqAQSk=
+ text: |
+ Set a mode where the time runs as fast as possible when a clock ISR occurs
+ while the IDLE thread is executing; this can significantly reduce simulation
+ times
+ type: build
+
+.. _BuildScriptItems:
+
+Script Items
+------------
+
+The ``build-type`` value shall be ``script``. The specialized item attributes
+are:
+
+configure-script
+ The `configure-script` value shall be Python code which is executed via
+ ``exec()`` in the context of the ``do_configure()`` method of the
+ ``wscript``.
+
+build-script
+ The `configure-script` value shall be Python code which is executed via
+ ``exec()`` in the context of the ``do_build()`` method of the ``wscript``.
+
+Example:
+
+.. code-block:: yaml
+
+ active: true
+ build-script: |
+ VersionControlKeyHeader.write(bld, "cpukit/include/version-vc-key.h")
+ build-type: script
+ configure-script: null
+ default: null
+ default-by-variant: []
+ derived: false
+ enabled-by: []
+ header: ''
+ level: 1.78
+ links: []
+ normative: true
+ order: 0
+ ref: ''
+ reviewed: qVAPTH3_HOgN4b3NqhaV1YOxhE9sXPS-W7t_IclXsvE=
+ text: ''
+ type: build
+
+.. _BuildStartFileItems:
+
+Start File Items
+----------------
+
+The ``build-type`` value shall be ``start-file``. The specialized item
+attributes are:
+
+asflags
+ The `asflags` value shall be a list of options for the assembler. They are
+ used to assemble the sources of this item.
+
+cppflags
+ See :ref:`cppflags <BuildAttrCppflags>`.
+
+destination
+ See :ref:`destination <BuildAttrDestination>`.
+
+includes
+ See :ref:`includes <BuildAttrIncludes>`.
+
+source
+ See :ref:`source <BuildAttrSource>`.
+
+target
+ See :ref:`target <BuildAttrTarget>`.
+
+Example:
+
+.. code-block:: yaml
+
+ active: true
+ asflags: []
+ build-type: start-file
+ cppflags: []
+ derived: true
+ destination: ${BSP_LIBDIR}/start.o
+ enabled-by: []
+ header: |
+ SPARC start file
+ includes: []
+ level: 1.0
+ links: []
+ normative: true
+ order: 0
+ ref: ''
+ reviewed: vs5yXA5jsmGfCK_ILflnbvKbUh_0xjaPaioC1thByCM=
+ source:
+ - bsps/sparc/shared/start/start.S
+ target: start.o
+ text: ''
+ type: build
+
+.. _BuildTestProgramItems:
+
+Test Program Items
+------------------
+
+The ``build-type`` value shall be ``test-program``. Test programs may use
+additional objects provided by :ref:`BuildObjectsItems`. The specialized item
+attributes are:
+
+cflags
+ See :ref:`cflags <BuildAttrCflags>`.
+
+cppflags
+ See :ref:`cppflags <BuildAttrCppflags>`.
+
+cxxflags
+ See :ref:`cxxflags <BuildAttrCxxflags>`.
+
+features
+ The `features` value shall be ``waf`` build features for this test program.
+
+includes
+ See :ref:`includes <BuildAttrIncludes>`.
+
+source
+ See :ref:`source <BuildAttrSource>`.
+
+stlib
+ The `stlib` value shall be a list of external static libraries used to link
+ this test program, e.g. ``m`` for ``libm.a``.
+
+target
+ See :ref:`target <BuildAttrTarget>`.
+
+use
+ The `use` value shall be a list of internal static libraries used to link
+ this test program, e.g. ``z`` for ``libz.a``.
+
+Example:
+
+.. code-block:: yaml
+
+ active: true
+ build-type: test-program
+ cflags: []
+ cppflags: []
+ cxxflags: []
+ derived: false
+ enabled-by: []
+ features: c cprogram
+ header: ''
+ includes: []
+ level: 1.0
+ links: []
+ normative: true
+ order: 0
+ ref: ''
+ reviewed: -GEWOVo01puXkp-o3dhk_mIBnBtD9Cl5TKAixNaD3GE=
+ source:
+ - testsuites/samples/ticker/init.c
+ - testsuites/samples/ticker/tasks.c
+ stlib: []
+ target: testsuites/samples/ticker.exe
+ text: ''
+ type: build
+ use: []
+
+.. _BuildHowto:
+
+Howtos
+======
+
+This section presents how to do common maintenance tasks in the build system.
+
+Find the Right Item
+-------------------
+
+TODO
+
+Create a BSP Family
+-------------------
+
+TODO
+
+Add a BSP Variant to a BSP Family
+---------------------------------
+
+TODO
+
+Add a BSP Option
+----------------
+
+TODO
+
+Add a Test Program
+------------------
+
+TODO
+
+Add a Library
+-------------
+
+TODO
diff --git a/eng/index.rst b/eng/index.rst
index 802eec9..59d2088 100644
--- a/eng/index.rst
+++ b/eng/index.rst
@@ -30,6 +30,7 @@ RTEMS Software Engineering (|version|)
management
test-plan
test-framework
+ build-system
release-mgmt
users-manuals
license-requirements
diff --git a/images/eng/build-deps.dot b/images/eng/build-deps.dot
new file mode 100644
index 0000000..8f83a0c
--- /dev/null
+++ b/images/eng/build-deps.dot
@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: CC-BY-SA-4.0
+
+# Copyright (C) 2019 embedded brains GmbH
+
+digraph {
+ size="4";
+ tg [label="Test Group", style=filled, fillcolor=green];
+ t0 [label="Test Program 0", style=filled, fillcolor=red];
+ t1 [label="Test Program 1", style=filled, fillcolor=red];
+ tn [label="Test Program n", style=filled, fillcolor=red];
+ lb [label="librtemsbsp.a", style=filled, fillcolor=magenta];
+ lc [label="librtemscpu.a", style=filled, fillcolor=magenta];
+ b0 [label="BSP 0", style=filled, fillcolor=orange];
+ b1 [label="BSP 1", style=filled, fillcolor=orange];
+ bn [label="BSP n", style=filled, fillcolor=orange];
+ bo0 [label="BSP 0 bspopts.h", style=filled, fillcolor=brown];
+ o0 [label="BSP 0 Option 0", style=filled, fillcolor=yellow];
+ o1 [label="BSP 0 Option 1", style=filled, fillcolor=yellow];
+ on [label="BSP 0 Option n", style=filled, fillcolor=yellow];
+ abi [label="BSP 0 ABI Flags", style=filled, fillcolor=blue];
+ s0 [label="BSP 0 Source 0", style=filled, fillcolor=cyan];
+ s1 [label="BSP 0 Source 1", style=filled, fillcolor=cyan];
+ sn [label="BSP 0 Source n", style=filled, fillcolor=cyan];
+ c0 [label="CPU Source 0", style=filled, fillcolor=cyan];
+ c1 [label="CPU Source 1", style=filled, fillcolor=cyan];
+ cn [label="CPU Source n", style=filled, fillcolor=cyan];
+ rankdir=LR
+ tg -> t0
+ tg -> t1
+ tg -> tn
+ t0 -> lb
+ t0 -> lc
+ t1 -> lb
+ t1 -> lc
+ tn -> lb
+ tn -> lc
+ lb -> b0
+ lb -> b1
+ lb -> bn
+ b0 -> s0
+ b0 -> s1
+ b0 -> sn
+ s0 -> abi
+ s1 -> abi
+ sn -> abi
+ c0 -> abi
+ c1 -> abi
+ cn -> abi
+ bo0 -> o0
+ bo0 -> o1
+ bo0 -> on
+ s0 -> bo0
+ s1 -> bo0
+ sn -> bo0
+ lc -> c0
+ lc -> c1
+ lc -> cn
+}
diff --git a/images/eng/build-deps2.dot b/images/eng/build-deps2.dot
new file mode 100644
index 0000000..28d900e
--- /dev/null
+++ b/images/eng/build-deps2.dot
@@ -0,0 +1,47 @@
+# SPDX-License-Identifier: CC-BY-SA-4.0
+
+# Copyright (C) 2019 embedded brains GmbH
+
+digraph {
+ size="4";
+ tg [label="Test Group", style=filled, fillcolor=green];
+ t0 [label="Test Program 0", style=filled, fillcolor=red];
+ t1 [label="Test Program 1", style=filled, fillcolor=red];
+ tn [label="Test Program n", style=filled, fillcolor=red];
+ lc [label="librtemscpu.a", style=filled, fillcolor=magenta];
+ b0 [label="BSP 0", style=filled, fillcolor=orange];
+ b1 [label="BSP 1", style=filled, fillcolor=orange];
+ bn [label="BSP n", style=filled, fillcolor=orange];
+ bo [label="BSP bspopts.h", style=filled, fillcolor=brown];
+ o0 [label="BSP 0 Option 0", style=filled, fillcolor=yellow];
+ o1 [label="BSP 0 Option 1", style=filled, fillcolor=yellow];
+ on [label="BSP 0 Option n", style=filled, fillcolor=yellow];
+ abi [label="BSP 0 ABI Flags", style=filled, fillcolor=blue];
+ s0 [label="BSP 0 Source 0", style=filled, fillcolor=cyan];
+ s1 [label="BSP 0 Source 1", style=filled, fillcolor=cyan];
+ sn [label="BSP 0 Source n", style=filled, fillcolor=cyan];
+ c0 [label="CPU Source 0", style=filled, fillcolor=cyan];
+ c1 [label="CPU Source 1", style=filled, fillcolor=cyan];
+ cn [label="CPU Source n", style=filled, fillcolor=cyan];
+ rankdir=LR
+ subgraph {
+ b0 -> s0
+ b0 -> s1
+ b0 -> sn
+ b0 -> abi
+ b0 -> o0
+ b0 -> o1
+ b0 -> on
+ b0 -> bo
+ }
+ subgraph {
+ lc -> c0
+ lc -> c1
+ lc -> cn
+ }
+ subgraph {
+ tg -> t0
+ tg -> t1
+ tg -> tn
+ }
+}
--
2.16.4
More information about the devel
mailing list