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

[Gedare Bloom]

On Tue, Jun 8, 2021 at 5:37 AM Christian Mauderer <oss at c-mauderer.de> wrote:
>
> 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).
>

This is satisfactory to me. At least for now, this pattern should be
well-documented/generalized for all BSPs though.

> 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), ...).
>
We should avoid the explicit listing, unless it is a completely
auto-generated manual, as mentioned elsewhere. For now, I'm fine with
instructing the user how to generate those build configuration
options, since they would need to be doing that to build rtems anyway.

> 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.
>
No, let's not do that.

Gedare