<div dir="ltr"><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Ah OK. Can Richi hold the changes locally until we work through the process to<br>bring this work into the project?</blockquote><div>Yes, it'd be at least two weeks before I test my all changes and send a patch.  </div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Mon, Jul 13, 2020 at 5:22 AM Chris Johns <<a href="mailto:chrisj@rtems.org">chrisj@rtems.org</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">On 8/7/20 3:35 pm, Sebastian Huber wrote:<br>
> Hello Chris,<br>
> <br>
> thanks for the detailed response.<br>
> <br>
> On 08/07/2020 03:55, Chris Johns wrote:<br>
>> Hi Sebastian,<br>
>><br>
>> Thank you for this patch. I am sorry but I would like to see this central repo<br>
>> issue resolved before any generated files are added to any of the project's<br>
>> repos.<br>
>><br>
>> I understand to some level the path you are taking and moving along but these<br>
>> generated files are coming from a personal repo that has changes, processes and<br>
>> tools that are not being reviewed. I think it would be wise for us to agree on<br>
>> what is behind all this before we agree to what is being generated.<br>
> <br>
> I rescheduled some work to be able to provide this patch earlier. Richi Dubey<br>
> asked a couple of questions with respect to the scheduler implementation and<br>
> some of them are related to how application configuration options define<br>
> internal scheduler data structures. So, It would be nice to be able to reference<br>
> them in Doxygen. You can review this patch independent from the way it is produced.<br>
<br>
Ah OK. Can Richi hold the changes locally until we work through the process to<br>
bring this work into the project?<br>
<br>
>> On 7/7/20 9:25 pm, Sebastian Huber wrote:<br>
>>> This patch adds the application configuration option documentation generated<br>
>>> from specification items:<br>
>>><br>
>>> <a href="https://git.rtems.org/sebh/rtems-qual.git/tree/spec/if/acfg" rel="noreferrer" target="_blank">https://git.rtems.org/sebh/rtems-qual.git/tree/spec/if/acfg</a><br>
>> <gulp> That is a lot of files. I am not sure I am ready to accept documentation<br>
>> as a lot of small files. I am happy to be persuaded otherwise.<br>
>><br>
>> It is not clear to me if these YAML files generate documentation, headers, are<br>
>> requirements or something else.<br>
> <br>
> Each application configuration option and group is provided as a separate<br>
> specification item (YAML file). The type of the specification items is<br>
> documented here:<br>
> <br>
> <a href="https://docs.rtems.org/branches/master/eng/req/items.html" rel="noreferrer" target="_blank">https://docs.rtems.org/branches/master/eng/req/items.html</a><br>
<br>
Thanks. I have looked at this before and it is detailed. The documentation make<br>
sense and it is a really good starting place.<br>
<br>
> <a href="https://docs.rtems.org/branches/master/eng/req/items.html#spectypeapplicationconfigurationoptionitemtype" rel="noreferrer" target="_blank">https://docs.rtems.org/branches/master/eng/req/items.html#spectypeapplicationconfigurationoptionitemtype</a><br>
> <br>
> Application configuration options are things on their own, so they have their<br>
> own items. This enables other items to reference application configuration<br>
> options. <br>
<br>
When you say `item` is this in relation to the qual tools and the `item` as<br>
documented?<br>
<br>
> In the manual you have now a lot more cross references for example if<br>
> you compare it with the RTEMS 4.11 documentation. Items have their own history<br>
> and can be reviewed individually. I see this as benefits.<br>
<br>
Yes there are benefits and I am not questioning these benefits. Once we depend<br>
on these generated files we also depend on what generates these so this should<br>
be our focus. Accepting the output into the repos means accepting the tools that<br>
generated these files.<br>
<br>
I see the process to get the repo accepted being related to the high level<br>
architectural and procedure things this change brings. There needs to be a<br>
review, consideration and discussion.<br>
<br>
>> There is nothing I can see in them that defines<br>
>> their `role` or `roles`.<br>
> <br>
> When you look at an item<br>
> <br>
> <a href="https://git.rtems.org/sebh/rtems-qual.git/tree/spec/if/acfg/message-buffer-memory.yml" rel="noreferrer" target="_blank">https://git.rtems.org/sebh/rtems-qual.git/tree/spec/if/acfg/message-buffer-memory.yml</a><br>
> <br>
> <br>
> you see attributes like<br>
> <br>
> |type: interface ||interface-type: appl-config-option ||appl-config-option-type:<br>
> integer This defines the type of an item. I corresponds to the specification<br>
> type refinement:<br>
> <a href="https://docs.rtems.org/branches/master/eng/req/items.html#spectyperootitemtype" rel="noreferrer" target="_blank">https://docs.rtems.org/branches/master/eng/req/items.html#spectyperootitemtype</a><br>
> <a href="https://docs.rtems.org/branches/master/eng/req/items.html#spectypeinterfaceitemtype" rel="noreferrer" target="_blank">https://docs.rtems.org/branches/master/eng/req/items.html#spectypeinterfaceitemtype</a><br>
> <a href="https://docs.rtems.org/branches/master/eng/req/items.html#spectypeapplicationconfigurationoptionitemtype" rel="noreferrer" target="_blank">https://docs.rtems.org/branches/master/eng/req/items.html#spectypeapplicationconfigurationoptionitemtype</a><br>
> <a href="https://docs.rtems.org/branches/master/eng/req/items.html#spectypeapplicationconfigurationvalueoptionitemtype" rel="noreferrer" target="_blank">https://docs.rtems.org/branches/master/eng/req/items.html#spectypeapplicationconfigurationvalueoptionitemtype</a><br>
> All attributes and the value types are defined by specification item types. The<br>
> specification item types are defined by specification items:<br>
> <a href="https://git.rtems.org/sebh/rtems-qual.git/tree/spec/spec" rel="noreferrer" target="_blank">https://git.rtems.org/sebh/rtems-qual.git/tree/spec/spec</a> The type information is<br>
> used to generate the documentation in the RTEMS Software Engineering manual and<br>
> is used to verify that the items are in line with the type specification:<br>
> <a href="https://git.rtems.org/sebh/rtems-qual.git/tree/specverify.py" rel="noreferrer" target="_blank">https://git.rtems.org/sebh/rtems-qual.git/tree/specverify.py</a> |||||<br>
> <br>
>> If they do generate files how does that happen and how<br>
>> are those generated header files related to the C code they are an interface<br>
>> for?<br>
> <br>
> The Doxygen header file of this patch is not read by the C compiler. However, I<br>
> would like to generate also the API header files from specification items. I am<br>
> now able to generate <rtems.h> and all header files included by this header<br>
> which define API elements. About 585 items describe the API defined by <rtems.h>:<br>
> <br>
> <a href="https://git.rtems.org/sebh/rtems-qual.git/tree/spec/if/rtems" rel="noreferrer" target="_blank">https://git.rtems.org/sebh/rtems-qual.git/tree/spec/if/rtems</a><br>
> <br>
> This item describes rtems_semaphore_create():<br>
> <br>
> <a href="https://git.rtems.org/sebh/rtems-qual.git/tree/spec/if/rtems/sem/create.yml" rel="noreferrer" target="_blank">https://git.rtems.org/sebh/rtems-qual.git/tree/spec/if/rtems/sem/create.yml</a><br>
> <br>
> It is worth to have a closer look at this item.<br>
> <br>
> The interface specification items can be used to generate the header files with<br>
> Doxygen markup, Sphinx sources for the manuals, and an Interface Control<br>
> Document (ICD, a document required by ECSS).<br>
<br>
OK. It will require a bit of time to take in the detail and to understand the<br>
connections.<br>
<br>
>> How do I keep each piece in sync?<br>
> The basic work flow would be to update an item, then call one or more scripts,<br>
> run make or ./waf, or whatever, to generate the derived content. This will alter<br>
> the state of Git submodules. Then you create patch sets from the changes in the<br>
> submodules and send them for review. After acceptance you push the changes and<br>
> update the submodules.<br>
<br>
OK, so there is no pulling changes in the repos back, it is a one way process?<br>
<br>
>> A compile error seems a long way from one<br>
>> of these YAML files.<br>
> Yes, this is a bit harder to correlate. I don't think this will be a real issue.<br>
> It is for example easy to figure out with "grep" which item is relevant.<br>
<br>
I think you are right, coding interfaces is not done often and I think our users<br>
are please this is the case.<br>
<br>
>> For example, if I was to add a YAML file to this directory I have no idea where<br>
>> I look to find the naming, what roles are assumed, how it integrates into the<br>
>> existing documentation, doxygen or header files? I also have no idea how I would<br>
>> create a new API header file? What if I push a new header file to the rtems.git<br>
>> repo with a new #include in rtems.h. Does a regenerate over write it?<br>
> <br>
> Yes, this is a real issue. We have to think about how we want to continue with<br>
> the specification stuff in general. I see clear benefits to generate content<br>
> from a project-wide master data set to avoid the copy and paste stuff we have<br>
> right now.<br>
<br>
Yes this is true. We have evolved to have a number of places that share common<br>
data, the version is an example. A script to update an item is workable but<br>
fragile and I think it would not be long before we start to consider a master<br>
repo that lets us work across the various locations in a unified manner.<br>
<br>
>> It seems to me the key is the central repo and how it functions, how easy or<br>
>> hard it is to learn about it and how well it will work in practice. A key<br>
>> concern is taking it from a single person repo, ie you, to a project wide repo<br>
>> with concurrent updates ad lots of moving pieces. It is easy to ask these<br>
>> questions and I appreciate they are not all easy to answer but I think we need<br>
>> to try.<br>
> My approach would be to document common tasks for the every day RTEMS maintenance:<br>
> <br>
> <a href="https://docs.rtems.org/branches/master/eng/req/howto.html" rel="noreferrer" target="_blank">https://docs.rtems.org/branches/master/eng/req/howto.html</a><br>
> <br>
> You also have to consider the future rate of change. The API parts, application<br>
> configuration options, and glossary terms for example are all things which don't<br>
> change every week.<br>
<br>
I think we will end up using something like nuggit ..<br>
<br>
<a href="https://github.com/monacca1/nuggit" rel="noreferrer" target="_blank">https://github.com/monacca1/nuggit</a><br>
<br>
I have not looked into this tool yet. I suspect while it is just you working in<br>
the repo it is fine but I wonder how managing a few submodules will go once it<br>
is opened up and there are multiple people working in the files.<br>
<br>
> With respect to the code which generates the content. It is written in Python 3<br>
> with the new Python guidelines in mind:<br>
> <br>
> <a href="https://docs.rtems.org/branches/master/eng/python-devel.html" rel="noreferrer" target="_blank">https://docs.rtems.org/branches/master/eng/python-devel.html</a><br>
> <br>
> It uses yapf for the code formatting. It uses the static analyzers flake8, mypy,<br>
> and pylint. There are unit tests using pytest which yield 100% branch coverage.<br>
> It is not finished work. It was not reviewed, but I think it is a good start.<br>
<br>
I have taken a quick look over the Python code and looks great. I can see it is<br>
all formatted to the new standard and the tests look good. Thank you for this.<br>
<br>
Following the standards we have and creating tests makes it easier for us to<br>
accept the code. As a result I do not think we need to review it is detail.<br>
<br>
>>> The header file is generated by the following script and module:<br>
>>><br>
>>> <a href="https://git.rtems.org/sebh/rtems-qual.git/tree/spec2doc.py" rel="noreferrer" target="_blank">https://git.rtems.org/sebh/rtems-qual.git/tree/spec2doc.py</a><br>
>>><br>
>>> <a href="https://git.rtems.org/sebh/rtems-qual.git/tree/rtemsqual/applconfig.py" rel="noreferrer" target="_blank">https://git.rtems.org/sebh/rtems-qual.git/tree/rtemsqual/applconfig.py</a><br>
>>><br>
>>> The module uses currently a hack to resolve references external to specification<br>
>>> items, e.g. sections in the RTEMS Classic API Guide or URLs.  I think we need<br>
>>> specialized specification items for these external references.<br>
>> I do not understand what this means?<br>
> <br>
> Being able to generate Doxygen markup and Sphinx sources from the same data set<br>
> was not a small task. We talk here about several weeks of work. You can't take<br>
> it for granted that this works at all in an area with many cross references such<br>
> as the application configuration options. For all external references I had to<br>
> create a table in the source code:<br>
> <br>
> <a href="https://git.rtems.org/sebh/rtems-qual.git/tree/rtemsqual/applconfig.py#n327" rel="noreferrer" target="_blank">https://git.rtems.org/sebh/rtems-qual.git/tree/rtemsqual/applconfig.py#n327</a><br>
> <br>
> <a href="https://git.rtems.org/sebh/rtems-qual.git/tree/rtemsqual/applconfig.py#n381" rel="noreferrer" target="_blank">https://git.rtems.org/sebh/rtems-qual.git/tree/rtemsqual/applconfig.py#n381</a><br>
> <br>
> This is not really elegant.<br>
<br>
The table can be moved to an external file when ready.<br>
<br>
> <br>
>><br>
>>> Sebastian Huber (1):<br>
>>>    Document application configuration options<br>
>>><br>
>>>   cpukit/doxygen/appl-config.h | 4133 ++++++++++++++++++++++++++++++++++<br>
>>>   1 file changed, 4133 insertions(+)<br>
>>>   create mode 100644 cpukit/doxygen/appl-config.h<br>
>> Is this information found in the user manual as well? I am struggling to<br>
>> understand the relationships and what is being presented where.<br>
> <br>
> Yes, you find it here for example:<br>
> <br>
> <a href="https://docs.rtems.org/branches/master/c-user/config/general.html" rel="noreferrer" target="_blank">https://docs.rtems.org/branches/master/c-user/config/general.html</a><br>
> <br>
<br>
Thanks<br>
Chris<br>
_______________________________________________<br>
devel mailing list<br>
<a href="mailto:devel@rtems.org" target="_blank">devel@rtems.org</a><br>
<a href="http://lists.rtems.org/mailman/listinfo/devel" rel="noreferrer" target="_blank">http://lists.rtems.org/mailman/listinfo/devel</a></blockquote></div>