[PATCH rtems 2/2] bsps/imxrt: Simplify linkcmds and make it flexible

[Christian Mauderer]

Hello Chris,

On 08/06/2021 12:05, Chris Johns wrote:
> On 8/6/21 7:08 pm, Christian Mauderer wrote:
>> Hello Chris,
>>
>> On 08/06/2021 05:07, Chris Johns wrote:
>>> On 7/6/21 6:40 pm, Christian Mauderer wrote:> I think the Options don't need
>>> documentation changes because the options in the
>>>> waf based build system are now documented directly in the yaml files and printed
>>>> if you generate the default config.
>>>
>>> Hmm I am not sure I agree with the premise the YAML is the documentation. The
>>> user manual exists for this purpose and user wanting to explore RTEMS would look
>>> there rather than cloning the repo, running commands etc.
>>
>> The alternative would be to duplicate documentation of the BSP options in the
>> user manual. And (manual) duplication is always a bad idea if you ask me. Or
>> move the description from the yaml to the documentation entirely which means
>> that you need to pick the correct version of the documentation for the sources.
>> It also means that you have to look up the meaning of each option in the right
>> version of the manual instead of in the default config.
> 
> At the moment users need to work too hard to find it. Maybe manual changes can
> be added if someone wants to added them until a better solution is provided. I
> think it is better that blocking changes until it is.

At the moment for the i.MXRT BSP all BSP options are documented in the 
yaml files. In the user manual there is a section

===

8.2.10.1. Build Configuration Options

Please see the documentation of the IMXRT_* and BSP_* configuration 
options for that. You can generate a default set of options with:

./waf bsp_defaults --rtems-bsps=arm/imxrt1052 > config.ini

===

That's one command that a user has to call to see the BSP options 
including their meaning _and_ get a default config.ini (a file that he 
needs anyway also not necessarily with all options).

There are some (very few) BSPs that have a list of Build Configuration 
Options in the manual. The i.mx (without RT) and the i386 are two of 
them. The description of the options is slightly different from the ones 
in the yaml files and I really don't want to review them. A lot of other 
BSPs don't have any description at all (for example beagle, xen, 
raspberrypi, nearly all powerpc, qemu A53 (aarch64), ...).

If you want, I can replace the call in the manual by a inlined 
config.ini for that BSP. I _hope_ that everyone remembers that he has to 
update that file in the manual too. But I wouldn't guarantee that. I 
think the call is a lot more user friendly than an possibly outdated 
user manual where the exact right version has to be used.

>> I think the only reasonable option (with the current structure) would be to
>> somehow automatically generate that documentation part. For example by creating
>> the default BSP config.ini for each BSP and adding it to the user manual. But
>> that has to be an automatic process. Otherwise it will be out of date right from
>> the beginning.
> 
> .... or something else. I don't think we need to solve the problem here and now
> as we do not have enough support in rtems.git to handle it.
> 
> I do not want to depend on rtems-central at this point in time. It needs to
> mature, it needs to exist for a while and be supported before we can integrate it.

If you _want_ config.ini files in the manuals (or some other format for 
the options) I think the repo would be exactly the right place to hold a 
script to generate that kind of stuff. How should it become mature 
otherwise?

> 
>>> I accept the current defaults etc work flow is a good place to start for the waf
>>> conversion project but we need to do a lot more to make accessing the YAML
>>> easier. The wscript contains the only rtems.git repo means to read the YAML and
>>> the pickled data and that limits how we can change and evolve this.
>>>
>>
>> We could merge documentation and code again. From my point of view that would
>> make it simpler to add documentation for new features right when they are
>> implemented and there would be always the right version for a source commit. I
>> don't really know the reason why it was split up in 2015 / 2016 so we would have
>> to look that up before discussing further into that direction. Additionally it
>> would need discussion how and where (for example) network stacks would be
>> documented.
> 
> It was split because it did not work as it did not handle the whole project so
> please lets not be distracted revisiting old problems.

That argument is about the same point that I added as a contra argument 
in the second sentence: I wouldn't be sure where to put the additional 
mauals. I'm not a fan of split documentation and code but I'm OK with 
not discussing that here and now.

Best regards

Christian

> 
> Chris
>