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

[John Snow]

On 4/29/21 9:40 AM, marcandre.lureau@redhat.com wrote:
> From: Marc-André Lureau <marcandre.lureau@redhat.com>
>
> Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>

I see why the docs are here at the end now -- you change the AST first, 
and then the meaning of the conditional string second. You didn't wanna 
write two versions.

I'm fine with that personally, but I'm not the one to convince.

> ---
>   docs/devel/qapi-code-gen.txt | 27 ++++++++++++++++-----------
>   1 file changed, 16 insertions(+), 11 deletions(-)
>
> diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt
> index edaaf7ec40..4a3fd02723 100644
> --- a/docs/devel/qapi-code-gen.txt
> +++ b/docs/devel/qapi-code-gen.txt
> @@ -780,26 +780,31 @@ downstream command __com.redhat_drive-mirror.
>   === Configuring the schema ===
>   
>   Syntax:
> -    COND = STRING
> -         | [ STRING, ... ]
> +    COND = CFG-ID
> +         | [ COND, ... ]
> +         | { '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.
> +    CFG-ID = STRING
> +
> +All definitions take an optional 'if' member. Its value must be a string, a 
> list
> +of strings or an object with a single member 'all', 'any' or 'not'. A string is
> +shorthand for a list containing just that string. A list is a shorthand for a
> +'all'-member object. The C code generated for the definition will then be 
> guarded
> +by an #if precessor expression generated from that condition: 'all': [COND, 
> ...]
> +will generate '(COND && ...)', 'any': [COND, ...] '(COND || ...)', 'not': COND 
> '!COND'.
>   
>   Example: a conditional struct
>   
>    { 'struct': 'IfStruct', 'data': { 'foo': 'int' },
> -   'if': ['CONFIG_FOO', '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

Tentatively pretty OK with the gist of the changes in this series in 
general; pending possibly some re-ordering/re-basing changes and the 
like to make various things flow better that I don't personally insist on.

Biggest personal concerns are:

- Inlining C-specific information into schema.py
- Inlining C-generators into the IfPredicate classes
- Building IfPredicate trees directly in expr.py

Tested-by: John Snow <jsnow@redhat.com>

--js