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
_______________________________________________
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel
