New Build System Status

[Sebastian Huber]

On 27/11/2019 00:59, Chris Johns wrote:
> On 27/11/19 2:07 am, Sebastian Huber wrote:
>> I updated the build system documentation.
> 
> Thank you.

Thanks for having a look at it and the very helpful comments.

> 
>> It is now sufficiently good to get integrated from my point of view.
> 
> Excellent and well done. However it cannot be merged until the question I raised
> here is resolved ...
> 
> https://lists.rtems.org/pipermail/devel/2019-November/056225.html
> 
> Joel raised it and it is valid so I feel we should to wait until he responds. Joel?
> 
>> https://ftp.rtems.org/pub/rtems/people/sebh/eng.pdf
> 
> This is a really great start piece of work. To have this from the start is so good.
> 
> 8.1 Should the install location be specified rather than referencing something
> that is not specified?
> 
> "Configurable things which define what is built and how the artefacts are
> configured are intended to be placed in configuration files."
> 
> to
> 
> " Configurable things which define what is built and how the artefacts are
> configured are intended to be placed in configuration files that can be
> configuration controlled."
> 
> "The wscript file should know nothing ..."
> 
> to
> 
> "The waf build script file called wscript should know nothing ..."

Ok, I reworded this.

> 8.2
> 
> What is the link to "RTEMS User Manual"? I think inter-document links are
> problematic. Referencing the docs.rtems.org can result in version mismatches.

I think links to other documents are quite helpful. We should find a way 
to make them happen. For example a script could adjust the URLs in a 
release branch from the "master" to the right version. Maybe add the 
manuals to

common/rtemsdomain.py

and reference chapters/sections by name?

> 
> Should there be a simple overview sequence picture ...
> 
>    -----------------------------
>            get defaults
>    -----------------------------
>                 |
>                 +-- edit --+
>                 |          |
>    -----------------------------
>             configure
>    -----------------------------
>                 |
>    -----------------------------
>               build
>    -----------------------------
>                 |
>    -----------------------------
>              install
>    -----------------------------
> 
> ... as I think it would help explain the next sections?

I think this is already covered by the User Manual content.

> 
> 8.3 Please add an example of the command. I know what you mean however I suspect
> I am one of a few who would.

Ok, done.

> 
> 8.5
> 
> Order: In the trade off case how does someone get a current picture of this
> structure so they can determine a suitable value?

Ok, I restructured this section.

> 
> cflags: Can any valid cflags be added here? Are there constraints on cflags and
> any of the other types of flags listed? 

Currently, no variable substitution is performed on the flags. This is a 
fine tuning option. We should measure how much performance the 
substitution would cost.

> The example uses [], is this a valid
> YAML syntax?

Yes, of course. It denotes an empty list.

> 
> 8.5.2 The cflags page reference is wrong, I see cflags on page 118 and not 116.

Hm, this looks like a Sphinx/Tex bug. The figure moves into the space 
between the label and the content.

.. _BuildAttrCflags:

cflags
     The `cflags` value shall be a list of options for the C compiler.

I don't know how to fix this.

> 
> format: Does a valid python string mean suitable indenting? Does it need to meet
> any required indent level or is in self contained?

I added an example.

> 
> name: Any constraints such as valid characters that can be used?

I added a regular expression.

> 
>> https://ftp.rtems.org/pub/rtems/people/sebh/user.pdf
> 
> Nice work.
> 
> The last step does another `cd` to the RTEMS source, could this be confusing?

I think the boxes should be self-contained, e.g. if a command needs to 
be called in a certain directory, then this should be ensured.

> 
> 7.3 More external links. Same issue as the eng manual, I cannot see how these
> can be made to work for any build of documentation at any location for the
> various types of output we generate.

See above.

-- 
Sebastian Huber, embedded brains GmbH

Address : Dornierstr. 4, D-82178 Puchheim, Germany
Phone   : +49 89 189 47 41-16
Fax     : +49 89 189 47 41-09
E-Mail  : sebastian.huber at embedded-brains.de
PGP     : Public key available on request.

Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.