[PATCH 2/3] eng: Add build system chapter

[Sebastian Huber]

On 03/07/2020 17:09, Gedare Bloom wrote:

> On Fri, Jul 3, 2020 at 3:18 AM Sebastian Huber
> <sebastian.huber at embedded-brains.de>  wrote:
>> Update #3818.
>> ---
>>   eng/build-system.rst     | 406 +++++++++++++++++++++++++++++++++++++++
>>   eng/index.rst            |   1 +
>>   images/eng/bld-bsp.dot   |  33 ++++
>>   images/eng/bld-bsp.pdf   | Bin 0 -> 15044 bytes
>>   images/eng/bld-bsp.png   | Bin 0 -> 32435 bytes
>>   images/eng/bld-bsp2.dot  |  42 ++++
>>   images/eng/bld-bsp2.pdf  | Bin 0 -> 16314 bytes
>>   images/eng/bld-bsp2.png  | Bin 0 -> 33936 bytes
>>   images/eng/bld-deps.dot  |  59 ++++++
>>   images/eng/bld-deps.pdf  | Bin 0 -> 18559 bytes
>>   images/eng/bld-deps.png  | Bin 0 -> 18098 bytes
>>   images/eng/bld-deps2.dot |  52 +++++
>>   images/eng/bld-deps2.pdf | Bin 0 -> 18241 bytes
>>   images/eng/bld-deps2.png | Bin 0 -> 40695 bytes
> Maybe better to add the binary files in a patch first by themselves,
> separate from the ascii. Easier to review, merge, etc.
Yes, sorry.
>
>> [...]
>> +Configurable things which depend on the host computer environment such as paths
>> +to tools are intended to be passed as command line options to the ``waf``
>> +command line tool.  Configurable things which define what is built and how the
>> +artefacts are configured are intended to be placed in configuration files that
>> +can be configuration controlled.  The ``waf`` build script file called
>> +``wscript`` file should know nothing about the layout of the sources.  What is
> file repetitive, can remove one of them from "script file" or "file should"
Yes this sounds awkward.
>
>> [...]
>> +UID Naming Conventions
>> +======================
>> +
>> +Use the following patterns for :ref:`UID names <ReqEngIdent>`:
>> +
>> +abi
>> +    Use the name ``abi`` for BSP ABI flags.
> Is this not a prefix, it is unique `abi`?

Yes, it is not a prefix.

find spec -name abi.yml | wc
      84      84    4455

>
>> +
>> +bsp*
>> +    Use the prefix ``bsp`` for base BSPs.
>> +
>> +cfg*
>> +    Use the prefix ``cfg`` for ``config.h`` header options.
>> +
>> +grp*
>> +    Use the prefix ``grp`` for groups.
>> +
>> +lib*
>> +    Use the prefix ``lib`` for libraries.
>> +
>> +linkcmds*
>> +    Use the prefix ``linkcmds`` for linker command files.
>> +
>> +obj*
>> +    Use the prefix ``obj`` for objects.  Use
>> +
>> +    * ``objmpci`` for objects which are enabled by ``RTEMS_MULTIPROCESSING``,
>> +
>> +    * ``objnet`` for objects which are enabled by ``RTEMS_NETWORKING``,
>> +
>> +    * ``objnetnosmp`` for objects which are enabled by ``RTEMS_NETWORKING`` and
>> +      not ``RTEMS_SMP``, and
>> +
>> +    * ``objsmp`` for objects which are enabled by ``RTEMS_SMP``.
>> +
>> +opt*
>> +    Use the prefix ``opt`` for options.  Use
>> +
>> +    * ``optclk*`` for options which have something to do with the clock
>> +      driver,
>> +
>> +    * ``optcon*`` for options which have something to do with the console
>> +      driver,
>> +
>> +    * ``optirq*`` for options which have something to do with interrupt
>> +      processing,
>> +
>> +    * ``opt*mem*`` for options which have something to do with the memory
>> +      configuration, map, settings, etc., and
> Is the * between opt and mem supposed to be there?
I think the name patterns need some rethinking. They originate from the 
Doorstop era which produced quite long path names. Now we can be a bit 
more descriptive. I will send a v2.
>
>> +
>> +    * ``optosc*`` for options which have something to do with oscillators.
>> +
>> +start
>> +    Use the name ``start`` for BSP start files.
> Also is not a prefix?

Yes, also not a prefix:

find spec -name start.yml | wc
      60      60    3244