| Message ID | 20180321115211.17937-31-marcandre.lureau@redhat.com |
|---|---|
| State | New |
| Headers | show |
| Series | qapi: add #if pre-processor conditions to generated code | expand |
Marc-André Lureau <marcandre.lureau@redhat.com> writes: > Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com> > --- > docs/devel/qapi-code-gen.txt | 38 ++++++++++++++++++++++++++++++++++++ > 1 file changed, 38 insertions(+) > > diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt > index a569d24745..eec52e63e5 100644 > --- a/docs/devel/qapi-code-gen.txt > +++ b/docs/devel/qapi-code-gen.txt > @@ -728,6 +728,44 @@ Example: Red Hat, Inc. controls redhat.com, and may therefore add a > downstream command __com.redhat_drive-mirror. > > > +=== Configuring the schema === > + > +Top-level QAPI expressions and various type expressions listed below Not sure about "and various type expressions listed below". Perhaps it's better to start with explaining just top-level conditionals, then explain member conditionals separately. > +can take an 'if' key. The value must be a string or a list of > +string. The corresponding generated code will then guard the inclusion s/string/strings/ > +of that member in the larger struct or function with #if IFCOND > +(or several #if lines for a list), where IFCOND is the value of the > +'if' key. > + > +'struct', 'enum', 'union', 'alternate', 'command' and 'event' > +top-level QAPI expressions can take an 'if' keyword like: > + > +{ 'struct': 'IfStruct', 'data': { 'foo': 'int' }, > + 'if': 'defined(IFCOND)' } > + > +Where a member can normally be defined with a single string value as its > +type, it is also possible to supply a dictionary with both 'type' and > +'if' keys. > + > +{ 'struct': 'IfStruct', 'data': > + { 'foo': 'int', > + 'bar': { 'type': 'int', 'if': 'defined(IFCOND)'} } } > + > +An enum value can be replaced by a dictionary with a 'name' and a 'if' > +key: > + > +{ 'enum': 'IfEnum', 'data': > + [ 'foo', > + { 'name' : 'bar', 'if': 'defined(IFCOND)' } ] } > + > +Please note that you are responsible to ensure that the C code will > +compile with an arbitrary combination of conditions, since the > +generators are unable to check it at this point. > + > +The presence of 'if' keys in the schema is reflected through to the > +introspection output depending on the build configuration. > + > + > == Client JSON Protocol introspection == > > Clients of a Client JSON Protocol commonly need to figure out what Missing: how 'if' affects generated code. Want me to try my hand at a fixup?
diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt index a569d24745..eec52e63e5 100644 --- a/docs/devel/qapi-code-gen.txt +++ b/docs/devel/qapi-code-gen.txt @@ -728,6 +728,44 @@ Example: Red Hat, Inc. controls redhat.com, and may therefore add a downstream command __com.redhat_drive-mirror. +=== Configuring the schema === + +Top-level QAPI expressions and various type expressions listed below +can take an 'if' key. The value must be a string or a list of +string. The corresponding generated code will then guard the inclusion +of that member in the larger struct or function with #if IFCOND +(or several #if lines for a list), where IFCOND is the value of the +'if' key. + +'struct', 'enum', 'union', 'alternate', 'command' and 'event' +top-level QAPI expressions can take an 'if' keyword like: + +{ 'struct': 'IfStruct', 'data': { 'foo': 'int' }, + 'if': 'defined(IFCOND)' } + +Where a member can normally be defined with a single string value as its +type, it is also possible to supply a dictionary with both 'type' and +'if' keys. + +{ 'struct': 'IfStruct', 'data': + { 'foo': 'int', + 'bar': { 'type': 'int', 'if': 'defined(IFCOND)'} } } + +An enum value can be replaced by a dictionary with a 'name' and a 'if' +key: + +{ 'enum': 'IfEnum', 'data': + [ 'foo', + { 'name' : 'bar', 'if': 'defined(IFCOND)' } ] } + +Please note that you are responsible to ensure that the C code will +compile with an arbitrary combination of conditions, since the +generators are unable to check it at this point. + +The presence of 'if' keys in the schema is reflected through to the +introspection output depending on the build configuration. + + == Client JSON Protocol introspection == Clients of a Client JSON Protocol commonly need to figure out what
Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com> --- docs/devel/qapi-code-gen.txt | 38 ++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+)