diff mbox series

[v2] qconfig: Improve the documentation

Message ID 20261003-qconfigdoc-v2-1-b2338cdd8a35@gmail.com
State New
Delegated to: Tom Rini
Headers show
Series [v2] qconfig: Improve the documentation | expand

Commit Message

Massimo Pegorer Oct. 3, 2026, 5 p.m. UTC 
Specify where the database is created and under what name. Add text
value lookup examples, including quoting, escaping and regular
expression cases. Update other examples, or just their output, in the
section documenting -f option usage. Trivial fixes.

Signed-off-by: Massimo Pegorer <massimo.pegorer+oss@gmail.com>
---
Changes in v2:
- Reword and add details.
- Update examples about -f options, or their output.
- Link to v1: https://patch.msgid.link/20261003-qconfigdoc-v1-1-9dac84b3ef75@gmail.com

To: u-boot@lists.u-boot-project.org
To: Simon Glass <sjg@chromium.org>
Cc: Tom Rini <trini@konsulko.com>
---
 doc/develop/qconfig.rst | 40 +++++++++++++++++++++++++++++++---------
 1 file changed, 31 insertions(+), 9 deletions(-)


---
base-commit: bd2f5794b7e24c62042abb1921f9c2039b920e02
change-id: 20261003-qconfigdoc-fe844c4f241f

Best regards,
--  
Massimo Pegorer <massimo.pegorer+oss@gmail.com>

Comments

Simon Glass Oct. 9, 2026, 7:20 a.m. UTC | #1 
Hi Massimo,

On 2026-10-03T17:00:18, Massimo Pegorer <massimo.pegorer+oss@gmail.com> wrote:
> qconfig: Improve the documentation
>
> Specify where the database is created and under what name. Add text
> value lookup examples, including quoting, escaping and regular
> expression cases. Update other examples, or just their output, in the
> section documenting -f option usage. Trivial fixes.
>
> Signed-off-by: Massimo Pegorer <massimo.pegorer+oss@gmail.com>
>
> doc/develop/qconfig.rst | 40 +++++++++++++++++++++++++++++++---------
>  1 file changed, 31 insertions(+), 9 deletions(-)

> diff --git a/doc/develop/qconfig.rst b/doc/develop/qconfig.rst
> @@ -81,22 +84,41 @@ Each term is CONFIG name, with or without a tilde (~) prefix. The tool searches
> -    tools/qconfig.py -f SCSI ~BLK
> -    3 matches
> -    pg_wcom_seli8_defconfig highbank_defconfig pg_wcom_expu1_defconfig
> +    ./tools/qconfig.py -f PCIE1 ~PCIE2
> +    10 matches
> +    MPC8548CDS_36BIT MPC8548CDS MPC8548CDS_legacy kmcent2

The sentence above still says 'to find boards which enabled
CONFIG_SCSI but not CONFIG_BLK', which no longer matches the example.
Please can you update it to refer to CONFIG_PCIE1 and CONFIG_PCIE2?

> diff --git a/doc/develop/qconfig.rst b/doc/develop/qconfig.rst
> @@ -81,22 +84,41 @@ Each term is CONFIG name, with or without a tilde (~) prefix. The tool searches
> +String values can be searched for, too, including regular expressions, but
> +taking care of needed quoting and escaping. The values stored in the database
> +are the ones from the Kconfig files, before expansion. Moreover, since they are
> +stored with their double quotes, the quotes must be part of the pattern.

This is much clearer, thanks. One point I might have missed earlier:
the pattern must match the whole value, since defconfig_matches() uses
fullmatch(). Otherwise a reader might expect something like '"arch/.*'
to work. Please can you add a sentence about this?

Regards,
Simon
diff mbox series

Patch

diff --git a/doc/develop/qconfig.rst b/doc/develop/qconfig.rst
index a18f32470ca..8a1827e2701 100644
--- a/doc/develop/qconfig.rst
+++ b/doc/develop/qconfig.rst
@@ -24,11 +24,14 @@  You may need to install 'python3-asteval' for the 'asteval' module.
 How does it work?
 -----------------
 
+The tool must be run at the top of the source directory.
+
 When building a database (`-b`), this tool runs configuration and builds
 include/autoconf.mk for every defconfig.  The config options defined in Kconfig
-appear in the .config file (unless they are hidden because of unmet dependency.)
+appear in the .config file (unless they are hidden because of unmet dependency).
 On the other hand, the config options defined by board headers are seen
-in include/autoconf.mk.
+in include/autoconf.mk.  The tool stores the database in a file named qconfig.db
+at the top of the source directory.
 
 When resyncing defconfigs (`-s`) the .config is synced by "make savedefconfig"
 and the defconfig is updated with it.
@@ -81,22 +84,41 @@  Each term is CONFIG name, with or without a tilde (~) prefix. The tool searches
 for boards which match the CONFIG name, or do not match if tilde is used. For
 example, to find boards which enabled CONFIG_SCSI but not CONFIG_BLK::
 
-    tools/qconfig.py -f SCSI ~BLK
-    3 matches
-    pg_wcom_seli8_defconfig highbank_defconfig pg_wcom_expu1_defconfig
+    ./tools/qconfig.py -f PCIE1 ~PCIE2
+    10 matches
+    MPC8548CDS_36BIT MPC8548CDS MPC8548CDS_legacy kmcent2
+    ls1012afrwy_tfa_SECURE_BOOT ls1012afrwy_tfa ls1012aqds_tfa_SECURE_BOOT
+    ls1012aqds_tfa ls1012ardb_tfa_SECURE_BOOT ls1012ardb_tfa
 
 It is also possible to search for particular values. For example, this finds all
 boards with an empty string for `CONFIG_DEFAULT_FDT_FILE`::
 
     ./tools/qconfig.py -f DEFAULT_FDT_FILE=\"\"
-    1092 matches
+    1229 matches
     ...
 
 This finds boards which have a value for SYS_MAXARGS other than 64::
 
     ./tools/qconfig.py -f ~SYS_MAXARGS=64
-    cfg CONFIG_SYS_MAXARGS
-    281 matches
+    296 matches
+    ...
+
+String values can be searched for, too, including regular expressions, but
+taking care of needed quoting and escaping. The values stored in the database
+are the ones from the Kconfig files, before expansion. Moreover, since they are
+stored with their double quotes, the quotes must be part of the pattern.
+Enclosing the pattern with single quotes makes the shell pass the double quotes
+and backslashes through unchanged. For example::
+
+    ./tools/qconfig.py -f TPL_LDSCRIPT='"arch/arm/cpu/u-boot-spl.lds"'
+    0 matches
+
+    ./tools/qconfig.py -f TPL_LDSCRIPT='"arch/.*/cpu/u-boot-spl.lds"'
+    22 matches
+    ...
+
+    ./tools/qconfig.py -f TPL_LDSCRIPT='"arch/\$\(ARCH\)/cpu/u-boot-spl.lds"'
+    22 matches
     ...
 
 
@@ -245,4 +267,4 @@  Available options
 
 To see the complete list of supported options, run::
 
-  tools/qconfig.py -h
+    ./tools/qconfig.py -h