[PATCH 0/2] qapi/qapi-schema: Clarify the dependency relationship

[PATCH 0/2] qapi/qapi-schema: Clarify the dependency relationship

[Zhao Liu]

Hi,

At present, the correctness of the dependencies of JSON files is ensured
by the order in which they are listed, but in general, the mixing of
multiple files and the lack of clear guidelines for ordering them is not
friendly to extending and maintaining.

Therefore, I have a proposal to manually categorize and sort JSON files
generation order by dependencies/dependency hierarchy, to improve the
readability and maintainability of qapi-schema.json.

Welcome your feedback!

Thanks and Best Regards,
Zhao
---
Zhao Liu (2):
  qapi: Reorder and categorize json files in qapi-schema.json
  qapi: List block-core.json in qapi-schema.json

 qapi/qapi-schema.json | 100 +++++++++++++++++++++++++++++-------------
 1 file changed, 69 insertions(+), 31 deletions(-)

-- 
2.34.1

[PATCH 1/2] qapi: Reorder and categorize json files in qapi-schema.json

[Zhao Liu]

Currently, the C code is generated sequentially in the order of the QAPI
json files in qapi-schema.json. This requires that the included file
must be listed first, before the file that includes it.

The current files' order implicitly fulfills this requirement, but
unclear dependency relationship makes it unfriendly for subsequent
dependency handling/adding new files.

While dependencies can be better handled by adding a sorting algorithm
to scripts/qapi/gen.py, to simplify and visualize the current API JSON
dependencies, sort them manually and categorize by dependency hierarchy.

Based on this, the new files should be placed in the corresponding
sections according to the dependencies/dependency hierarchy.

Signed-off-by: Zhao Liu <zhao1.liu@intel.com>
---
 qapi/qapi-schema.json | 100 +++++++++++++++++++++++++++++-------------
 1 file changed, 69 insertions(+), 31 deletions(-)

diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json
index 5e33da7228f2..57ea6bcb33e9 100644
--- a/qapi/qapi-schema.json
+++ b/qapi/qapi-schema.json
@@ -38,45 +38,83 @@
 
 # Documentation generated with qapi-gen.py is in source order, with
 # included sub-schemas inserted at the first include directive
-# (subsequent include directives have no effect).  To get a sane and
-# stable order, it's best to include each sub-schema just once, or
-# include it first right here.
+# (subsequent include directives have no effect). Please place the
+# file correctly in the following sections according to the
+# dependencies.
+#
+# To get a sane and stable order, it's best to include each sub-schema
+# just once, or include it first right here.
 
-{ 'include': 'error.json' }
+# Section 1. Files without dependencies.
+
+{ 'include': 'acpi.json' }
+{ 'include': 'audio.json' }
+{ 'include': 'authz.json' }
 { 'include': 'common.json' }
-{ 'include': 'sockets.json' }
-{ 'include': 'run-state.json' }
+{ 'include': 'compat.json' }
+{ 'include': 'control.json' }
 { 'include': 'crypto.json' }
-{ 'include': 'job.json' }
-{ 'include': 'block.json' }
-{ 'include': 'block-export.json' }
-{ 'include': 'char.json' }
+{ 'include': 'cryptodev.json' }
+{ 'include': 'cxl.json' }
 { 'include': 'dump.json' }
-{ 'include': 'net.json' }
 { 'include': 'ebpf.json' }
-{ 'include': 'rocker.json' }
-{ 'include': 'tpm.json' }
-{ 'include': 'ui.json' }
-{ 'include': 'authz.json' }
-{ 'include': 'migration.json' }
-{ 'include': 'transaction.json' }
-{ 'include': 'trace.json' }
-{ 'include': 'compat.json' }
-{ 'include': 'control.json' }
+{ 'include': 'error.json' }
 { 'include': 'introspect.json' }
-{ 'include': 'qom.json' }
-{ 'include': 'qdev.json' }
+{ 'include': 'job.json' }
 { 'include': 'machine-common.json' }
-{ 'include': 'machine.json' }
-{ 'include': 'machine-target.json' }
-{ 'include': 'replay.json' }
-{ 'include': 'yank.json' }
-{ 'include': 'misc.json' }
 { 'include': 'misc-target.json' }
-{ 'include': 'audio.json' }
-{ 'include': 'acpi.json' }
 { 'include': 'pci.json' }
+{ 'include': 'rocker.json' }
+{ 'include': 'run-state.json' }
+{ 'include': 'sockets.json' }
 { 'include': 'stats.json' }
+{ 'include': 'tpm.json' }
+{ 'include': 'trace.json' }
 { 'include': 'virtio.json' }
-{ 'include': 'cryptodev.json' }
-{ 'include': 'cxl.json' }
+{ 'include': 'yank.json' }
+
+# Section 2. Files with 1-level dependencies.
+#
+# All their dependencies are listed in the section 1.
+
+# include sockets.json
+{ 'include': 'char.json' }
+# include machine-common.json
+{ 'include': 'machine-target.json' }
+# include common.json, machine-common.json
+{ 'include': 'machine.json' }
+# include common.json, sockets.json
+{ 'include': 'migration.json' }
+# include common.json
+{ 'include': 'misc.json' }
+# include sockets.json
+{ 'include': 'net.json' }
+# include common.json
+{ 'include': 'replay.json' }
+# include common.json, sockets.json
+{ 'include': 'ui.json' }
+
+# Section 3. Files with 2-level dependencies.
+#
+# Their dependencies are either listed in the previous sections, or are
+# not listed but include files from the previous section. At least one
+# dependency is a 1-level dependency file.
+
+# include sockets.json (section 1), block-core.json (not listed, 1-level
+# dependencies)
+{ 'include': 'block-export.json' }
+# include block-core.json (not listed, 1-level dependencies)
+{ 'include': 'block.json' }
+# include authz.json (section 1), common.json (section 1), crypto.json
+# (section 1), block-core.json (not listed, 1-level dependencies)
+{ 'include': 'qom.json' }
+# include block-core.json (not listed, 1-level dependencies)
+{ 'include': 'transaction.json' }
+
+# Section 4. Files with 3-level dependencies.
+#
+# All their dependencies are listed in the previous sections. At least one
+# dependency is from section 3.
+
+# include qom.json (section 3)
+{ 'include': 'qdev.json' }
-- 
2.34.1

[PATCH 2/2] qapi: List block-core.json in qapi-schema.json

[Zhao Liu]

Currently, block-core.json is not explicitly listed in the
qapi-schema.json.

To make the dependencies clearer, list block-core.json in section 2.

Signed-off-by: Zhao Liu <zhao1.liu@intel.com>
---
 qapi/qapi-schema.json | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json
index 57ea6bcb33e9..14196128c44e 100644
--- a/qapi/qapi-schema.json
+++ b/qapi/qapi-schema.json
@@ -77,6 +77,8 @@
 #
 # All their dependencies are listed in the section 1.
 
+# include common.json, crypto.json, job.json, sockets.json
+{ 'include': 'block-core.json' }
 # include sockets.json
 { 'include': 'char.json' }
 # include machine-common.json
@@ -96,19 +98,17 @@
 
 # Section 3. Files with 2-level dependencies.
 #
-# Their dependencies are either listed in the previous sections, or are
-# not listed but include files from the previous section. At least one
-# dependency is a 1-level dependency file.
+# All their dependencies are listed in the previous sections. At least one
+# dependency is from section 2.
 
-# include sockets.json (section 1), block-core.json (not listed, 1-level
-# dependencies)
+# include sockets.json (section 1), block-core.json (section 2)
 { 'include': 'block-export.json' }
-# include block-core.json (not listed, 1-level dependencies)
+# include block-core.json (section 2)
 { 'include': 'block.json' }
 # include authz.json (section 1), common.json (section 1), crypto.json
-# (section 1), block-core.json (not listed, 1-level dependencies)
+# (section 1), block-core.json (section 2)
 { 'include': 'qom.json' }
-# include block-core.json (not listed, 1-level dependencies)
+# include block-core.json (section 2)
 { 'include': 'transaction.json' }
 
 # Section 4. Files with 3-level dependencies.
-- 
2.34.1

Re: [PATCH 0/2] qapi/qapi-schema: Clarify the dependency relationship

[Zhao Liu]

Hi Eric and Markus,

Just a gentle poke. What do you think of this ordering?

Thanks,
Zhao

On Fri, May 17, 2024 at 02:27:46PM +0800, Zhao Liu wrote:
> Date: Fri, 17 May 2024 14:27:46 +0800
> From: Zhao Liu <zhao1.liu@intel.com>
> Subject: [PATCH 0/2] qapi/qapi-schema: Clarify the dependency relationship
> X-Mailer: git-send-email 2.34.1
> 
> Hi,
> 
> At present, the correctness of the dependencies of JSON files is ensured
> by the order in which they are listed, but in general, the mixing of
> multiple files and the lack of clear guidelines for ordering them is not
> friendly to extending and maintaining.
> 
> Therefore, I have a proposal to manually categorize and sort JSON files
> generation order by dependencies/dependency hierarchy, to improve the
> readability and maintainability of qapi-schema.json.
> 
> Welcome your feedback!
> 
> Thanks and Best Regards,
> Zhao
> ---
> Zhao Liu (2):
>   qapi: Reorder and categorize json files in qapi-schema.json
>   qapi: List block-core.json in qapi-schema.json
> 
>  qapi/qapi-schema.json | 100 +++++++++++++++++++++++++++++-------------
>  1 file changed, 69 insertions(+), 31 deletions(-)
> 
> -- 
> 2.34.1
>