From 7e1529501883ce8741d8689c150f589ab68a814f Mon Sep 17 00:00:00 2001 From: Paolo Bonzini Date: Fri, 7 Feb 2020 01:55:27 +0100 Subject: rename unstable-kconfig to unstable-keyval Discussions in #6524 have shown that there are various possible uses of the kconfig module and even disagreements in the exact file format between Python-based kconfiglib and the tools in Linux. Instead of trying to reconcile them, just rename the module to something less suggestive and leave any policy to meson.build files. In the future it may be possible to add some kind of parsing through keyword arguments such as bool_true, quoted_strings, etc. and possibly creation of key-value lists too. For now, configuration_data objects provide an easy way to access quoted strings. Note that Kconfig stores false as "absent" so it was already necessary to write "x.has_key('abc')" rather than the more compact "x['abc']". Therefore, having to use configuration_data does not make things much more verbose. --- docs/markdown/Kconfig-module.md | 52 -------------------------- docs/markdown/Keyval-module.md | 55 ++++++++++++++++++++++++++++ docs/markdown/snippets/keyval_kobject.md | 6 +++ docs/sitemap.txt | 2 +- docs/theme/extra/templates/navbar_links.html | 2 +- 5 files changed, 63 insertions(+), 54 deletions(-) delete mode 100644 docs/markdown/Kconfig-module.md create mode 100644 docs/markdown/Keyval-module.md create mode 100644 docs/markdown/snippets/keyval_kobject.md (limited to 'docs') diff --git a/docs/markdown/Kconfig-module.md b/docs/markdown/Kconfig-module.md deleted file mode 100644 index 5807f8d..0000000 --- a/docs/markdown/Kconfig-module.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -short-description: Unstable kconfig module -authors: - - name: Mark Schulte, Paolo Bonzini - years: [2017, 2019] - has-copyright: false -... - -# Unstable kconfig module - -This module parses Kconfig output files to allow use of kconfig -configurations in meson projects. - -**Note**: this does not provide kconfig frontend tooling to generate a -configuration. You still need something such as kconfig frontends (see -link below) to parse your Kconfig files, and then (after you've -chosen the configuration options), output a ".config" file. - - [kconfig-frontends]: http://ymorin.is-a-geek.org/projects/kconfig-frontends - -## Usage - -The module may be imported as follows: - -``` meson -kconfig = import('unstable-kconfig') -``` - -The following functions will then be available as methods on the object -with the name `kconfig`. You can, of course, replace the name -`kconfig` with anything else. - -### kconfig.load() - -This function loads a kconfig output file and returns a dictionary object. - -`kconfig.load()` makes no attempt at parsing the values in the -file. Therefore, true boolean values will be represented as the string "y" -and integer values will have to be converted with `.to_int()`. - -Kconfig frontends usually have ".config" as the default name for the -configuration file. However, placing the configuration file in the source -directory limits the user to one configuration per source directory. -In order to allow separate configurations for each build directory, as is -the Meson standard, `meson.build` should not hardcode ".config" as the -argument to `kconfig.load()`, and should instead make the argument to -`kconfig.load()` a [project build option](Build-options.md). - -* The first (and only) argument is the path to the configuration file to - load (usually ".config"). - -**Returns**: a [dictionary object](Reference-manual.md#dictionary-object). diff --git a/docs/markdown/Keyval-module.md b/docs/markdown/Keyval-module.md new file mode 100644 index 0000000..643265e --- /dev/null +++ b/docs/markdown/Keyval-module.md @@ -0,0 +1,55 @@ +--- +short-description: Unstable keyval module +authors: + - name: Mark Schulte, Paolo Bonzini + years: [2017, 2019] + has-copyright: false +... + +# keyval module + +This module parses files consisting of a series of `key=value` lines. One use +of this module is to load kconfig configurations in meson projects. + +**Note**: this does not provide kconfig frontend tooling to generate a +configuration. You still need something such as kconfig frontends (see +link below) to parse your Kconfig files, and then (after you've +chosen the configuration options), output a ".config" file. + + [kconfig-frontends]: http://ymorin.is-a-geek.org/projects/kconfig-frontends + +## Usage + +The module may be imported as follows: + +``` meson +keyval = import('unstable-keyval') +``` + +The following functions will then be available as methods on the object +with the name `keyval`. You can, of course, replace the name +`keyval` with anything else. + +### keyval.load() + +This function loads a file consisting of a series of `key=value` lines +and returns a dictionary object. + +`keyval.load()` makes no attempt at parsing the values in the file. +In particular boolean and integer values will be represented as strings, +and strings will keep any quoting that is present in the input file. It +can be useful to create a [`configuration_data()`](#configuration_data) +object from the dictionary and use methods such as `get_unquoted()`. + +Kconfig frontends usually have ".config" as the default name for the +configuration file. However, placing the configuration file in the source +directory limits the user to one configuration per source directory. +In order to allow separate configurations for each build directory, as is +the Meson standard, `meson.build` should not hardcode ".config" as the +argument to `kconfig.load()`, and should instead make the argument to +`kconfig.load()` a [project build option](Build-options.md). + +* The first (and only) argument is the path to the configuration file to + load (usually ".config"). + +**Returns**: a [dictionary object](Reference-manual.md#dictionary-object). diff --git a/docs/markdown/snippets/keyval_kobject.md b/docs/markdown/snippets/keyval_kobject.md new file mode 100644 index 0000000..4add23c --- /dev/null +++ b/docs/markdown/snippets/keyval_kobject.md @@ -0,0 +1,6 @@ +## `unstable-kconfig` module renamed to `unstable-keyval` + +The `unstable-kconfig` module is now renamed to `unstable-keyval`. +We expect this module to become stable once it has some usage experience, +specifically in the next or the following release + diff --git a/docs/sitemap.txt b/docs/sitemap.txt index 3ac138e..4029a60 100644 --- a/docs/sitemap.txt +++ b/docs/sitemap.txt @@ -48,7 +48,7 @@ index.md SourceSet-module.md Windows-module.md Cuda-module.md - Kconfig-module.md + Keyval-module.md Java.md Vala.md D.md diff --git a/docs/theme/extra/templates/navbar_links.html b/docs/theme/extra/templates/navbar_links.html index 6980f81..832bd2c 100644 --- a/docs/theme/extra/templates/navbar_links.html +++ b/docs/theme/extra/templates/navbar_links.html @@ -14,7 +14,7 @@ ("Hotdoc-module.html","Hotdoc"), \ ("i18n-module.html","i18n"), \ ("Icestorm-module.html","Icestorm"), \ - ("Kconfig-module.html","kconfig"), \ + ("Keyval-module.html","Keyval"), \ ("Pkgconfig-module.html","Pkgconfig"), \ ("Python-module.html","Python"), \ ("Python-3-module.html","Python 3"), \ -- cgit v1.1