Re: [PATCH v5 1/9] docs: update the documentation about schema configuration

["Marc-André Lureau" <marcandre.lureau@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 4242 bytes --]

Hi

On Tue, Jun 15, 2021 at 3:53 PM Markus Armbruster <armbru@redhat.com> wrote:

> marcandre.lureau@redhat.com writes:
>
> > From: Marc-André Lureau <marcandre.lureau@redhat.com>
> >
> > Update the documentation describing the changes in this series.
>
> Suggest to add "upfront" for clarity.
>

done


> >
> > Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
> > Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>
> > Tested-by: John Snow <jsnow@redhat.com>
> > ---
> >  docs/devel/qapi-code-gen.txt | 30 ++++++++++++++++++------------
> >  1 file changed, 18 insertions(+), 12 deletions(-)
> >
> > diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt
> > index c1cb6f987d..0162b73119 100644
> > --- a/docs/devel/qapi-code-gen.txt
> > +++ b/docs/devel/qapi-code-gen.txt
> > @@ -781,25 +781,31 @@ downstream command __com.redhat_drive-mirror.
> >
> >  Syntax:
> >      COND = STRING
> > -         | [ STRING, ... ]
> > +         | { 'all: [ COND, ... ] }
> > +         | { 'any: [ COND, ... ] }
> > +         | { 'not': COND }
> >
> >  All definitions take an optional 'if' member.  Its value must be a
> > -string or a list of strings.  A string is shorthand for a list
> > -containing just that string.  The code generated for the definition
> > -will then be guarded by #if STRING for each STRING in the COND list.
> > +string, or an object with a single member 'all', 'any' or 'not'.
> > +
> > +The C code generated for the definition will then be guarded by an #if
> > +preprocessing directive generated from that condition:
> > +
> > +   * STRING will generate #if defined(STRING)
> > +   * { 'all': [COND, ...] } will generate #if (COND && ...)
> > +   * { 'any': [COND, ...] } will generate #if (COND || ...)
> > +   * { 'not': COND } will generate #if !COND
>
> I know this is exactly what I suggested.  It gets the point across, but
> it's not quite accurate: the #if of course only at the root of the tree,
> not at every level.  Better, I think:
>
>    The C code generated for the definition will then be guarded by an #if
>    preprocessing directive with an operand generated from that condition:
>
>       * STRING will generate defined(STRING)
>       * { 'all': [COND, ...] } will generate (COND && ...)
>       * { 'any': [COND, ...] } will generate (COND || ...)
>       * { 'not': COND } will generate !COND
>
>
ok


> >
> >  Example: a conditional struct
> >
> >   { 'struct': 'IfStruct', 'data': { 'foo': 'int' },
> > -   'if': ['defined(CONFIG_FOO)', 'defined(HAVE_BAR)'] }
> > +   'if': { 'all': [ 'CONFIG_FOO', 'HAVE_BAR' ] } }
> >
> >  gets its generated code guarded like this:
> >
> > - #if defined(CONFIG_FOO)
> > - #if defined(HAVE_BAR)
> > + #if defined(CONFIG_FOO) && defined(HAVE_BAR)
> >   ... generated code ...
> > - #endif /* defined(HAVE_BAR) */
> > - #endif /* defined(CONFIG_FOO) */
> > + #endif /* defined(HAVE_BAR) && defined(CONFIG_FOO) */
> >
> >  Individual members of complex types, commands arguments, and
> >  event-specific data can also be made conditional.  This requires the
> > @@ -810,7 +816,7 @@ member 'bar'
> >
> >  { 'struct': 'IfStruct', 'data':
> >    { 'foo': 'int',
> > -    'bar': { 'type': 'int', 'if': 'defined(IFCOND)'} } }
> > +    'bar': { 'type': 'int', 'if': 'IFCOND'} } }
> >
> >  A union's discriminator may not be conditional.
> >
> > @@ -822,7 +828,7 @@ value 'bar'
> >
> >  { 'enum': 'IfEnum', 'data':
> >    [ 'foo',
> > -    { 'name' : 'bar', 'if': 'defined(IFCOND)' } ] }
> > +    { 'name' : 'bar', 'if': 'IFCOND' } ] }
> >
> >  Likewise, features can be conditional.  This requires the longhand
> >  form of FEATURE.
> > @@ -832,7 +838,7 @@ Example: a struct with conditional feature
> 'allow-negative-numbers'
> >  { 'struct': 'TestType',
> >    'data': { 'number': 'int' },
> >    'features': [ { 'name': 'allow-negative-numbers',
> > -                  'if': 'defined(IFCOND)' } ] }
> > +                  'if': 'IFCOND' } ] }
> >
> >  Please note that you are responsible to ensure that the C code will
> >  compile with an arbitrary combination of conditions, since the
>
>
>

-- 
Marc-André Lureau

[-- Attachment #2: Type: text/html, Size: 6452 bytes --]