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

[Christian Mauderer]

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.

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.

> 
> 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.

Best regards

Christian