[PATCH 1/3] build: Format build items

[Sebastian Huber]

On 18.01.23 22:58, Amar Takhar wrote:
> On 2023-01-17 08:39 +0100, Sebastian Huber wrote:
> <snip>
>>
>> The Python modules to work with specification items are in
>> rtems-central.git. This repository contains also a format specification
>> of the build items. We could add an action to a Github work flow to
>> check the build item format for pull requests and commits.
> 
> I don't chime in here very often but after seeing the recent changes I'm
> extremely confused.
> 
> There are now tools that sit outside of the RTEMS repository that now change
> source files in RTEMS?
> 
> I have never seen it done this way before.  What version of this tool have you
> used?  How can anyone in the future possibly debug this?

In rtems-central.git there are Python modules and scripts which generate 
source, header, and documentation files from specification items. This 
repository contains the pre-qualification support for RTEMS. By 
accident, a part of the build system uses also specification items. So, 
if you want to change the format of the items, you can use the tooling 
available in rtems-central.git to do this. An example is the recent 
merge of the "default" and "default-by-variant" attributes.

> 
> What should happen here is this tools should sit in the main repository.  Any
> required changes made and then a command run to generate new output:
> 
>    ./waf <somecommand>
> 
> This lets us know that the output in this commit was generated by code existing
> in the previous commit.  There is no need to version anything it's already done.
> 
> Having it sitting outside of the source repository makes debugging impossible.
> Case in point is the commit message here.  No explanation as to where these
> changes have come from.  No commit version.  I spent a very long time figuring
> out what was going on and I could not figure it out without digging through the
> lists.

The changes were made by a 10 liner throw away script. I could have done 
the changes also manually it would be just more work.

> 
> How is anyone in 5, 10, 15 years down the road going to sort through this?  What
> if I want to make a change in 10 years and regenerate.  It is impossible as I
> have no idea what's been done let alone where to look.

There is nothing to regenerate. The patch set contains simple format 
changes and a transformation of attributes.

However, your concern is still valid for the generated files, for example

https://github.com/RTEMS/rtems/blob/master/cpukit/include/rtems.h

which is generated from

https://github.com/RTEMS/rtems-central/blob/master/spec/rtems/if/header.yml

Most of the Classic API header files are generated from specification 
items. If nobody takes care that rtems-central.git is used and stays up 
to date the specification will get out of synchronization with rtems.git.

> 
> I'm not against the purpose of the tool or the work has been done but this is
> not the correct way to handle generated files within a repository if we want to
> maintain the ability to make changes or debug years down the line.

I would use a single repository for RTEMS just like the FreeBSD base 
system, but this is another discussion.

-- 
embedded brains GmbH
Herr Sebastian HUBER
Dornierstr. 4
82178 Puchheim
Germany
email: sebastian.huber at embedded-brains.de
phone: +49-89-18 94 741 - 16
fax:   +49-89-18 94 741 - 08

Registergericht: Amtsgericht München
Registernummer: HRB 157899
Vertretungsberechtigte Geschäftsführer: Peter Rasmussen, Thomas Dörfler
Unsere Datenschutzerklärung finden Sie hier:
https://embedded-brains.de/datenschutzerklaerung/