| Message ID | 20230523133117.2278587-1-kchamart@redhat.com |
|---|---|
| State | New |
| Headers | show |
| Series | [v2] docs: build-system: rename "default-configs" to "configs" | expand |
On Tue, May 23, 2023 at 03:31:17PM +0200, Kashyap Chamarthy wrote: [I missed to include version history under "---"; now done] > Commit 812b31d3f9 (configs: rename default-configs to configs and > reorganise, 2021-07-07) did the rename. > > Reflect that update also in the documentation. > > Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com> In v2: - Address Lei Wang's feedback from v1: https://lists.nongnu.org/archive/html/qemu-devel/2023-05/msg02988.html (I'd appreciate a closer look at the edits in docs/devel/kconfig.rst, to make sure I'm referring to the correct subdirectory where appropriate: configs/devices/ vs. configs/targets/. I read through the surrounding text to make the choice, but a second look would be helpful.) > docs/devel/build-system.rst | 12 +++++------ > docs/devel/kconfig.rst | 40 ++++++++++++++++++++----------------- > 2 files changed, 28 insertions(+), 24 deletions(-) > > diff --git a/docs/devel/build-system.rst b/docs/devel/build-system.rst > index 1894721743..20ebcc9ac6 100644 > --- a/docs/devel/build-system.rst > +++ b/docs/devel/build-system.rst > @@ -193,7 +193,7 @@ Target-dependent emulator sourcesets: > Each emulator also includes sources for files in the ``hw/`` and ``target/`` > subdirectories. The subdirectory used for each emulator comes > from the target's definition of ``TARGET_BASE_ARCH`` or (if missing) > - ``TARGET_ARCH``, as found in ``default-configs/targets/*.mak``. > + ``TARGET_ARCH``, as found in ``configs/targets/*.mak``. > > Each subdirectory in ``hw/`` adds one sourceset to the ``hw_arch`` dictionary, > for example:: > @@ -250,8 +250,8 @@ Utility sourcesets: > The following files concur in the definition of which files are linked > into each emulator: > > -``default-configs/devices/*.mak`` > - The files under ``default-configs/devices/`` control the boards and devices > +``configs/devices/*.mak`` > + The files under ``configs/devices/`` control the boards and devices > that are built into each QEMU system emulation targets. They merely contain > a list of config variable definitions such as:: > > @@ -260,11 +260,11 @@ into each emulator: > CONFIG_XLNX_VERSAL=y > > ``*/Kconfig`` > - These files are processed together with ``default-configs/devices/*.mak`` and > + These files are processed together with ``configs/devices/*.mak`` and > describe the dependencies between various features, subsystems and > device models. They are described in :ref:`kconfig` > > -``default-configs/targets/*.mak`` > +``configs/targets/*.mak`` > These files mostly define symbols that appear in the ``*-config-target.h`` > file for each emulator [#cfgtarget]_. However, the ``TARGET_ARCH`` > and ``TARGET_BASE_ARCH`` will also be used to select the ``hw/`` and > @@ -457,7 +457,7 @@ Built by Meson: > TARGET-NAME is again the name of a system or userspace emulator. The > config-devices.mak file is automatically generated by make using the > scripts/make_device_config.sh program, feeding it the > - default-configs/$TARGET-NAME file as input. > + configs/$TARGET-NAME file as input. > > ``config-host.h``, ``$TARGET_NAME-config-target.h``, ``$TARGET_NAME-config-devices.h`` > These files are used by source code to determine what features are > diff --git a/docs/devel/kconfig.rst b/docs/devel/kconfig.rst > index e3a544e463..73118e5106 100644 > --- a/docs/devel/kconfig.rst > +++ b/docs/devel/kconfig.rst > @@ -38,11 +38,11 @@ originated in the Linux kernel, though it was heavily simplified and > the handling of dependencies is stricter in QEMU. > > Unlike Linux, there is no user interface to edit the configuration, which > -is instead specified in per-target files under the ``default-configs/`` > +is instead specified in per-target files under the ``configs/target/`` > directory of the QEMU source tree. This is because, unlike Linux, > -configuration and dependencies can be treated as a black box when building > -QEMU; the default configuration that QEMU ships with should be okay in > -almost all cases. > +configuration and dependencies can be treated as a black box when > +building QEMU; the default configuration that QEMU ships with should be > +okay in almost all cases. > > The Kconfig language > -------------------- > @@ -103,11 +103,12 @@ directives can be included: > **default value**: ``default <value> [if <expr>]`` > > Default values are assigned to the config symbol if no other value was > - set by the user via ``default-configs/*.mak`` files, and only if > - ``select`` or ``depends on`` directives do not force the value to true > - or false respectively. ``<value>`` can be ``y`` or ``n``; it cannot > - be an arbitrary Boolean expression. However, a condition for applying > - the default value can be added with ``if``. > + set by the user via > + ``configs/devices/TARGETNAME-softmmu/*.mak`` files, and only > + if ``select`` or ``depends on`` directives do not force the value to > + true or false respectively. ``<value>`` can be ``y`` or ``n``; it > + cannot be an arbitrary Boolean expression. However, a condition for > + applying the default value can be added with ``if``. > > A configuration element can have any number of default values (usually, > if more than one default is present, they will have different > @@ -119,8 +120,8 @@ directives can be included: > This is similar to ``select`` as it applies a lower limit of ``y`` > to another symbol. However, the lower limit is only a default > and the "implied" symbol's value may still be set to ``n`` from a > - ``default-configs/*.mak`` files. The following two examples are > - equivalent:: > + ``configs/devices/TARGETNAME-softmmu/*.mak`` files. The following > + two examples are equivalent:: > > config FOO > bool > @@ -146,8 +147,9 @@ declares its dependencies in different ways: > bool > > Subsystems always default to false (they have no ``default`` directive) > - and are never visible in ``default-configs/*.mak`` files. It's > - up to other symbols to ``select`` whatever subsystems they require. > + and are never visible in ``configs/devices/TARGETNAME-softmmu/*.mak`` > + files. It's up to other symbols to ``select`` whatever subsystems > + they require. > > They sometimes have ``select`` directives to bring in other required > subsystems or buses. For example, ``AUX`` (the DisplayPort auxiliary > @@ -229,7 +231,8 @@ declares its dependencies in different ways: > cannot be started at all without it. It should be listed under > ``imply`` if (depending on the QEMU command line) the board may or > may not be started without it. Boards also default to false; they are > - enabled by the ``default-configs/*.mak`` for the target they apply to. > + enabled by the ``configs/targets/TARGETNAME-softmmu/*.mak`` for the > + target they apply to. > > **internal elements** > > @@ -241,18 +244,19 @@ declares its dependencies in different ways: > > Internal elements group code that is useful in several boards or > devices. They are usually enabled with ``select`` and in turn select > - other elements; they are never visible in ``default-configs/*.mak`` > - files, and often not even in the Makefile. > + other elements; they are never visible in > + ``configs/devices/TARGETNAME-softmmu/*.mak`` files, and often not even > + in the Makefile. > > Writing and modifying default configurations > -------------------------------------------- > > In addition to the Kconfig files under hw/, each target also includes > -a file called ``default-configs/TARGETNAME-softmmu.mak``. These files > +a file called ``configs/devices/TARGETNAME-softmmu.mak``. These files > initialize some Kconfig variables to non-default values and provide the > starting point to turn on devices and subsystems. > > -A file in ``default-configs/`` looks like the following example:: > +A file in ``configs/devices/`` looks like the following example:: > > # Default configuration for alpha-softmmu > > -- > 2.40.1 >
On 23/05/2023 15.31, Kashyap Chamarthy wrote: > Commit 812b31d3f9 (configs: rename default-configs to configs and > reorganise, 2021-07-07) did the rename. > > Reflect that update also in the documentation. > > Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com> > --- > docs/devel/build-system.rst | 12 +++++------ > docs/devel/kconfig.rst | 40 ++++++++++++++++++++----------------- > 2 files changed, 28 insertions(+), 24 deletions(-) > > diff --git a/docs/devel/build-system.rst b/docs/devel/build-system.rst > index 1894721743..20ebcc9ac6 100644 > --- a/docs/devel/build-system.rst > +++ b/docs/devel/build-system.rst ... > @@ -457,7 +457,7 @@ Built by Meson: > TARGET-NAME is again the name of a system or userspace emulator. The > config-devices.mak file is automatically generated by make using the > scripts/make_device_config.sh program, feeding it the > - default-configs/$TARGET-NAME file as input. > + configs/$TARGET-NAME file as input. This hunk does not apply anymore - but I think it can simply be dropped now. > ``config-host.h``, ``$TARGET_NAME-config-target.h``, ``$TARGET_NAME-config-devices.h`` > These files are used by source code to determine what features are > diff --git a/docs/devel/kconfig.rst b/docs/devel/kconfig.rst > index e3a544e463..73118e5106 100644 > --- a/docs/devel/kconfig.rst > +++ b/docs/devel/kconfig.rst > @@ -38,11 +38,11 @@ originated in the Linux kernel, though it was heavily simplified and > the handling of dependencies is stricter in QEMU. > > Unlike Linux, there is no user interface to edit the configuration, which > -is instead specified in per-target files under the ``default-configs/`` > +is instead specified in per-target files under the ``configs/target/`` I think the Kconfig-related files are rather the ones in configs/devices/ , so I'd use that directory here instead. > directory of the QEMU source tree. This is because, unlike Linux, > -configuration and dependencies can be treated as a black box when building > -QEMU; the default configuration that QEMU ships with should be okay in > -almost all cases. > +configuration and dependencies can be treated as a black box when > +building QEMU; the default configuration that QEMU ships with should be > +okay in almost all cases. Why did you change the above three lines? > The Kconfig language > -------------------- > @@ -103,11 +103,12 @@ directives can be included: > **default value**: ``default <value> [if <expr>]`` > > Default values are assigned to the config symbol if no other value was > - set by the user via ``default-configs/*.mak`` files, and only if > - ``select`` or ``depends on`` directives do not force the value to true > - or false respectively. ``<value>`` can be ``y`` or ``n``; it cannot > - be an arbitrary Boolean expression. However, a condition for applying > - the default value can be added with ``if``. > + set by the user via > + ``configs/devices/TARGETNAME-softmmu/*.mak`` files, and only > + if ``select`` or ``depends on`` directives do not force the value to > + true or false respectively. ``<value>`` can be ``y`` or ``n``; it > + cannot be an arbitrary Boolean expression. However, a condition for > + applying the default value can be added with ``if``. > > A configuration element can have any number of default values (usually, > if more than one default is present, they will have different > @@ -119,8 +120,8 @@ directives can be included: > This is similar to ``select`` as it applies a lower limit of ``y`` > to another symbol. However, the lower limit is only a default > and the "implied" symbol's value may still be set to ``n`` from a > - ``default-configs/*.mak`` files. The following two examples are > - equivalent:: > + ``configs/devices/TARGETNAME-softmmu/*.mak`` files. The following > + two examples are equivalent:: > > config FOO > bool > @@ -146,8 +147,9 @@ declares its dependencies in different ways: > bool > > Subsystems always default to false (they have no ``default`` directive) > - and are never visible in ``default-configs/*.mak`` files. It's > - up to other symbols to ``select`` whatever subsystems they require. > + and are never visible in ``configs/devices/TARGETNAME-softmmu/*.mak`` > + files. It's up to other symbols to ``select`` whatever subsystems > + they require. > > They sometimes have ``select`` directives to bring in other required > subsystems or buses. For example, ``AUX`` (the DisplayPort auxiliary > @@ -229,7 +231,8 @@ declares its dependencies in different ways: > cannot be started at all without it. It should be listed under > ``imply`` if (depending on the QEMU command line) the board may or > may not be started without it. Boards also default to false; they are > - enabled by the ``default-configs/*.mak`` for the target they apply to. > + enabled by the ``configs/targets/TARGETNAME-softmmu/*.mak`` for the Should be configs/devices/... here, too, I think. Thomas
On Wed, May 31, 2023 at 04:22:34PM +0200, Thomas Huth wrote: > On 23/05/2023 15.31, Kashyap Chamarthy wrote: > > Commit 812b31d3f9 (configs: rename default-configs to configs and > > reorganise, 2021-07-07) did the rename. > > > > Reflect that update also in the documentation. > > > > Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com> > > --- > > docs/devel/build-system.rst | 12 +++++------ > > docs/devel/kconfig.rst | 40 ++++++++++++++++++++----------------- > > 2 files changed, 28 insertions(+), 24 deletions(-) > > > > diff --git a/docs/devel/build-system.rst b/docs/devel/build-system.rst > > index 1894721743..20ebcc9ac6 100644 > > --- a/docs/devel/build-system.rst > > +++ b/docs/devel/build-system.rst > ... > > @@ -457,7 +457,7 @@ Built by Meson: > > TARGET-NAME is again the name of a system or userspace emulator. The > > config-devices.mak file is automatically generated by make using the > > scripts/make_device_config.sh program, feeding it the > > - default-configs/$TARGET-NAME file as input. > > + configs/$TARGET-NAME file as input. > > This hunk does not apply anymore - but I think it can simply be dropped now. Just for my own clarity, which precise part do you suggest to be dropped? > > ``config-host.h``, ``$TARGET_NAME-config-target.h``, ``$TARGET_NAME-config-devices.h`` > > These files are used by source code to determine what features are > > diff --git a/docs/devel/kconfig.rst b/docs/devel/kconfig.rst > > index e3a544e463..73118e5106 100644 > > --- a/docs/devel/kconfig.rst > > +++ b/docs/devel/kconfig.rst > > @@ -38,11 +38,11 @@ originated in the Linux kernel, though it was heavily simplified and > > the handling of dependencies is stricter in QEMU. > > Unlike Linux, there is no user interface to edit the configuration, which > > -is instead specified in per-target files under the ``default-configs/`` > > +is instead specified in per-target files under the ``configs/target/`` > > I think the Kconfig-related files are rather the ones in configs/devices/ , > so I'd use that directory here instead. I see, will fix. > > directory of the QEMU source tree. This is because, unlike Linux, > > -configuration and dependencies can be treated as a black box when building > > -QEMU; the default configuration that QEMU ships with should be okay in > > -almost all cases. > > +configuration and dependencies can be treated as a black box when > > +building QEMU; the default configuration that QEMU ships with should be > > +okay in almost all cases. > > Why did you change the above three lines? Oops. Accidental bad habit of re-wrapping text in a paragraph. (When editing a plain text file I periodically hit "gq}" -`vim` shortcut to re-wrap text.) [...] > > They sometimes have ``select`` directives to bring in other required > > subsystems or buses. For example, ``AUX`` (the DisplayPort auxiliary > > @@ -229,7 +231,8 @@ declares its dependencies in different ways: > > cannot be started at all without it. It should be listed under > > ``imply`` if (depending on the QEMU command line) the board may or > > may not be started without it. Boards also default to false; they are > > - enabled by the ``default-configs/*.mak`` for the target they apply to. > > + enabled by the ``configs/targets/TARGETNAME-softmmu/*.mak`` for the > > Should be configs/devices/... here, too, I think. Yep; noted. Will fix. Thanks for the review.
On 01/06/2023 10.17, Kashyap Chamarthy wrote: > On Wed, May 31, 2023 at 04:22:34PM +0200, Thomas Huth wrote: >> On 23/05/2023 15.31, Kashyap Chamarthy wrote: >>> Commit 812b31d3f9 (configs: rename default-configs to configs and >>> reorganise, 2021-07-07) did the rename. >>> >>> Reflect that update also in the documentation. >>> >>> Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com> >>> --- >>> docs/devel/build-system.rst | 12 +++++------ >>> docs/devel/kconfig.rst | 40 ++++++++++++++++++++----------------- >>> 2 files changed, 28 insertions(+), 24 deletions(-) >>> >>> diff --git a/docs/devel/build-system.rst b/docs/devel/build-system.rst >>> index 1894721743..20ebcc9ac6 100644 >>> --- a/docs/devel/build-system.rst >>> +++ b/docs/devel/build-system.rst >> ... >>> @@ -457,7 +457,7 @@ Built by Meson: >>> TARGET-NAME is again the name of a system or userspace emulator. The >>> config-devices.mak file is automatically generated by make using the >>> scripts/make_device_config.sh program, feeding it the >>> - default-configs/$TARGET-NAME file as input. >>> + configs/$TARGET-NAME file as input. >> >> This hunk does not apply anymore - but I think it can simply be dropped now. > > Just for my own clarity, which precise part do you suggest to be > dropped? The above line seems to be gone, so it does not need fixing anymore, I think. You'll see it when you rebase your patch. Thomas
diff --git a/docs/devel/build-system.rst b/docs/devel/build-system.rst index 1894721743..20ebcc9ac6 100644 --- a/docs/devel/build-system.rst +++ b/docs/devel/build-system.rst @@ -193,7 +193,7 @@ Target-dependent emulator sourcesets: Each emulator also includes sources for files in the ``hw/`` and ``target/`` subdirectories. The subdirectory used for each emulator comes from the target's definition of ``TARGET_BASE_ARCH`` or (if missing) - ``TARGET_ARCH``, as found in ``default-configs/targets/*.mak``. + ``TARGET_ARCH``, as found in ``configs/targets/*.mak``. Each subdirectory in ``hw/`` adds one sourceset to the ``hw_arch`` dictionary, for example:: @@ -250,8 +250,8 @@ Utility sourcesets: The following files concur in the definition of which files are linked into each emulator: -``default-configs/devices/*.mak`` - The files under ``default-configs/devices/`` control the boards and devices +``configs/devices/*.mak`` + The files under ``configs/devices/`` control the boards and devices that are built into each QEMU system emulation targets. They merely contain a list of config variable definitions such as:: @@ -260,11 +260,11 @@ into each emulator: CONFIG_XLNX_VERSAL=y ``*/Kconfig`` - These files are processed together with ``default-configs/devices/*.mak`` and + These files are processed together with ``configs/devices/*.mak`` and describe the dependencies between various features, subsystems and device models. They are described in :ref:`kconfig` -``default-configs/targets/*.mak`` +``configs/targets/*.mak`` These files mostly define symbols that appear in the ``*-config-target.h`` file for each emulator [#cfgtarget]_. However, the ``TARGET_ARCH`` and ``TARGET_BASE_ARCH`` will also be used to select the ``hw/`` and @@ -457,7 +457,7 @@ Built by Meson: TARGET-NAME is again the name of a system or userspace emulator. The config-devices.mak file is automatically generated by make using the scripts/make_device_config.sh program, feeding it the - default-configs/$TARGET-NAME file as input. + configs/$TARGET-NAME file as input. ``config-host.h``, ``$TARGET_NAME-config-target.h``, ``$TARGET_NAME-config-devices.h`` These files are used by source code to determine what features are diff --git a/docs/devel/kconfig.rst b/docs/devel/kconfig.rst index e3a544e463..73118e5106 100644 --- a/docs/devel/kconfig.rst +++ b/docs/devel/kconfig.rst @@ -38,11 +38,11 @@ originated in the Linux kernel, though it was heavily simplified and the handling of dependencies is stricter in QEMU. Unlike Linux, there is no user interface to edit the configuration, which -is instead specified in per-target files under the ``default-configs/`` +is instead specified in per-target files under the ``configs/target/`` directory of the QEMU source tree. This is because, unlike Linux, -configuration and dependencies can be treated as a black box when building -QEMU; the default configuration that QEMU ships with should be okay in -almost all cases. +configuration and dependencies can be treated as a black box when +building QEMU; the default configuration that QEMU ships with should be +okay in almost all cases. The Kconfig language -------------------- @@ -103,11 +103,12 @@ directives can be included: **default value**: ``default <value> [if <expr>]`` Default values are assigned to the config symbol if no other value was - set by the user via ``default-configs/*.mak`` files, and only if - ``select`` or ``depends on`` directives do not force the value to true - or false respectively. ``<value>`` can be ``y`` or ``n``; it cannot - be an arbitrary Boolean expression. However, a condition for applying - the default value can be added with ``if``. + set by the user via + ``configs/devices/TARGETNAME-softmmu/*.mak`` files, and only + if ``select`` or ``depends on`` directives do not force the value to + true or false respectively. ``<value>`` can be ``y`` or ``n``; it + cannot be an arbitrary Boolean expression. However, a condition for + applying the default value can be added with ``if``. A configuration element can have any number of default values (usually, if more than one default is present, they will have different @@ -119,8 +120,8 @@ directives can be included: This is similar to ``select`` as it applies a lower limit of ``y`` to another symbol. However, the lower limit is only a default and the "implied" symbol's value may still be set to ``n`` from a - ``default-configs/*.mak`` files. The following two examples are - equivalent:: + ``configs/devices/TARGETNAME-softmmu/*.mak`` files. The following + two examples are equivalent:: config FOO bool @@ -146,8 +147,9 @@ declares its dependencies in different ways: bool Subsystems always default to false (they have no ``default`` directive) - and are never visible in ``default-configs/*.mak`` files. It's - up to other symbols to ``select`` whatever subsystems they require. + and are never visible in ``configs/devices/TARGETNAME-softmmu/*.mak`` + files. It's up to other symbols to ``select`` whatever subsystems + they require. They sometimes have ``select`` directives to bring in other required subsystems or buses. For example, ``AUX`` (the DisplayPort auxiliary @@ -229,7 +231,8 @@ declares its dependencies in different ways: cannot be started at all without it. It should be listed under ``imply`` if (depending on the QEMU command line) the board may or may not be started without it. Boards also default to false; they are - enabled by the ``default-configs/*.mak`` for the target they apply to. + enabled by the ``configs/targets/TARGETNAME-softmmu/*.mak`` for the + target they apply to. **internal elements** @@ -241,18 +244,19 @@ declares its dependencies in different ways: Internal elements group code that is useful in several boards or devices. They are usually enabled with ``select`` and in turn select - other elements; they are never visible in ``default-configs/*.mak`` - files, and often not even in the Makefile. + other elements; they are never visible in + ``configs/devices/TARGETNAME-softmmu/*.mak`` files, and often not even + in the Makefile. Writing and modifying default configurations -------------------------------------------- In addition to the Kconfig files under hw/, each target also includes -a file called ``default-configs/TARGETNAME-softmmu.mak``. These files +a file called ``configs/devices/TARGETNAME-softmmu.mak``. These files initialize some Kconfig variables to non-default values and provide the starting point to turn on devices and subsystems. -A file in ``default-configs/`` looks like the following example:: +A file in ``configs/devices/`` looks like the following example:: # Default configuration for alpha-softmmu
Commit 812b31d3f9 (configs: rename default-configs to configs and reorganise, 2021-07-07) did the rename. Reflect that update also in the documentation. Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com> --- docs/devel/build-system.rst | 12 +++++------ docs/devel/kconfig.rst | 40 ++++++++++++++++++++----------------- 2 files changed, 28 insertions(+), 24 deletions(-)