diff --git a/doc/doxygen/src/kconfig/kconfig.md b/doc/doxygen/src/kconfig/kconfig.md index af782a7f14..65c9696db9 100644 --- a/doc/doxygen/src/kconfig/kconfig.md +++ b/doc/doxygen/src/kconfig/kconfig.md @@ -92,12 +92,6 @@ will not longer be overridable by means of CFLAGS (e.g. set on the compilation command or on a Makefile). Consider this if you are getting a 'redefined warning'. -## A note on the usage of the 'clean' command -When using Kconfig as the configurator for RIOT, configuration symbols may be -used in Makefiles through the build system. For this to work properly make -sure that when cleaning an application you call `make clean && make all`, -instead of `make clean all`. - --- # Integration into the build system {#kconfig-integration-into-build-system} @@ -134,27 +128,32 @@ Kconfig symbol as documented in [Appendix A](#kconfig-appendix-a). ### 2. Merging all configuration sources {#kconfig-steps-merge-configs} In this step configuration values are taken from multiple sources and merged -into a single `merged.config` configuration file. This file is temporary and is +into a single `out.config` configuration file. This file is temporary and is removed on clean. If the user needs to save a particular configuration set, a backup has to be saved (this can be done using the menuconfig interface) so it can be loaded later in this step. -To accomplish merging of multiple input files, the `mergeconfig` script is +To accomplish merging of multiple input files, the `genconfig` script is used. Note that **the order matters**: existing configuration values are merged in the order expressed in the input section, where the last value assigned to a parameter has the highest priority. If no configuration files are available all default values will be applied. -`merged.config` is the only configuration input for the `autoconf.h` in the +`out.config` is the only configuration input for the `autoconf.h` in the [generation step](#kconfig-steps-header-gen). +Additionally this step generates a file `out.config.d` which holds the +information of all the used Kconfig files in Makefile format. This file is +included by the build system and allows to re-trigger the generation of +`out.conf` whenever a Kconfig file is modified. + #### Input - Optional: - `$ (APPDIR)/app.config`: Application specific default configurations. - `$ (APPDIR)/user.config`: Configurations saved by user. #### Output -- `$ (GENERATED_DIR)/merged.config` file. +- `$ (GENERATED_DIR)/out.config` file. ### 3. Menuconfig execution (optional) Menuconfig is a graphical interface for software configuration. It is used for @@ -162,7 +161,7 @@ the configuration of the Linux kernel. This section explains the process that occurs when RIOT is being configured using the menuconfig interface. The main `Kconfig` file is used in this step to show the configurable -parameters of the system. Kconfig will filter innaplicable parameters (i.e. +parameters of the system. Kconfig will filter inapplicable parameters (i.e. parameters exposed by modules that are not being used) based on the file `$ (GENERATED_DIR)/Kconfig.dep` generated in step 1. @@ -176,26 +175,29 @@ information see Note that if Kconfig is not used to configure a module, the corresponding header files default values will be used. -`merged.config` is one of the inputs for menuconfig. This means that any +`out.config` is one of the inputs for menuconfig. This means that any configuration that the application defines in the `app.config` or a backup configuration from the user in `user.config` are taken into account on the first run (see [Appendix C](#kconfig-appendix-c)). In this step the user chooses configuration values (or selects the minimal -configuration) and saves it to the `merged.config` file. Here the user can +configuration) and saves it to the `out.config` file. Here the user can choose to save a backup configuration file for later at a different location (e.g. a `user.config` file in the application folder). +If any changes occur to `out.config`, the +[generation of autoconf.h](#kconfig-steps-header-gen) is executed automatically. + #### Input - `/Kconfig` file. - Optional: - `$ (APPDIR)/app.config` - `$ (APPDIR)/user.config` - - `$ (GENERATED_DIR)/merged.config` + - `$ (GENERATED_DIR)/out.config` #### Output -- Updated `$ (GENERATED_DIR)/merged.config` file. -- `$ (GENERATED_DIR)/merged.config.old` backup file. +- Updated `$ (GENERATED_DIR)/out.config` file. +- `$ (GENERATED_DIR)/out.config.old` backup file. ### 4. Generation of the autoconf.h header {#kconfig-steps-header-gen} With the addition of Kconfig a dependency has been added to the build @@ -205,30 +207,31 @@ that should be used to configure modules in RIOT: `CONFIG__`. In order to generate the `autoconf.h` file the `genconfig` script is used. -Inputs for this script are the main `Kconfig` file and `merged.config` +Inputs for this script are the main `Kconfig` file and `out.config` configuration file, which holds the selected values for the exposed parameters. #### Input: -- `$ (GENERATED_DIR)/merged.config` file. +- `$ (GENERATED_DIR)/out.config` file. - Main `Kconfig` file exposing configuration of modules. #### Output: - `$ (GENERATED_DIR)/autoconf.h` configuration header file. -- `$ (GENERATED_DIR)/out.config` file. +- Optional: + - `$ (GENERATED_DIR)/deps/*/*.h` header files that allow incremental builds ### Summary of files These files are defined in `kconfig.mk`. -| File | Description | -| ----------------- | ----------- | -| `Kconfig` | Defines configuration options of modules. | -| `Kconfig.dep` | Holds a list of the modules that are being compiled. | -| `app.config` | Holds default application configuration values. | -| `user.config` | Holds configuration values applied by the user. | -| `merged.config` | Holds configuration from multiple sources. Used to generate header. | -| `autoconf.h` | Header file containing the macros that applied the selected configuration. | -| `out.config` | Configuration file containing all the symbols defined in `autoconf.h`. | +| File | Description | +| ---------------| ----------- | +| `Kconfig` | Defines configuration options of modules. | +| `Kconfig.dep` | Holds a list of the modules that are being compiled. | +| `app.config` | Holds default application configuration values. | +| `user.config` | Holds configuration values applied by the user. | +| `out.config` | Configuration file containing all the symbols defined in `autoconf.h`. | +| `out.config.d` | Dependency file of `out.config` containing the list of Kconfig files used to generate it. | +| `autoconf.h` | Header file containing the macros that applied the selected configuration. | ## Kconfig symbols in Makefiles As '.config' files have Makefile syntax they can be included when building, @@ -254,10 +257,10 @@ application's Makefile. The symbols will not be defined until after including --- # Transition phase {#kconfig-transition-phase} ## Making configuration via Kconfig optional {#kconfig-configuration-optional} -During transition to the usage of Kconfig as the main configurator for RIOT, -the default behavior will be the traditional one: expose configuration options -in header files and use CFLAGS as inputs. To allow optional configuration via -Kconfig, a convention will be used when writing Kconfig files. +During transition to the usage of Kconfig as the main configuration tool for +RIOT, the default behavior will be the traditional one: expose configuration +options in header files and use CFLAGS as inputs. To allow optional +configuration via Kconfig, a convention will be used when writing Kconfig files. Modules should be contained in their own `menuconfig` entries, this way the user can choose to enable the configuration via Kconfig for an specific module. @@ -548,14 +551,18 @@ the menuconfig graphical interface or writing '.config' files by hand. As explained in the ['Configuration sources merging step'](#kconfig-steps-merge-configs) of the configuration process, configuration from multiple sources are loaded to -create a single `merged.config` file, and the order of merging matters: last +create a single `out.config` file, and the order of merging matters: last file has priority. -While editing values directly via '.config' files `merged.config` will be -re-built. Once the user decides to edit `merged.config` directly using -menuconfig, the file will not be re-built anymore, and any changes by manually -editing the source files will have no effect. To go back to manual edition -a `make clean` has to be issued in the application directory. +While editing values directly via '.config' files `out.config` will be +re-built. The user can also use menuconfig interface to modify the configuration +file (this is the recommended way, as it gives access to much more information +regarding dependencies and default values of the symbols). Menuconfig will +change `out.config` directly (a backup file `out.config.old` will be kept). + +**It is recommended to save backups of the configurations, as any change on the +configuration sources would re-trigger the merging process and overwrite +`out.config`.** ## Appendix D: A few key aspects while exposing a macro to Kconfig {#kconfig-appendix-d} A macro that holds a 0 or 1 is modelled in Kconfig as a `bool` symbol. References to this macro diff --git a/doc/doxygen/src/kconfig/kconfig_integration.svg b/doc/doxygen/src/kconfig/kconfig_integration.svg index da3afaf61b..060064b99b 100644 --- a/doc/doxygen/src/kconfig/kconfig_integration.svg +++ b/doc/doxygen/src/kconfig/kconfig_integration.svg @@ -1,3 +1,3 @@ -
$(USEMODULE)
$(USEPKG)
[Not supported by viewer]
Kconfig.dep
[Not supported by viewer]
merged.config
[Not supported by viewer]
menuconfig
[Not supported by viewer]
autoconf.h
[Not supported by viewer]
0
[Not supported by viewer]
1
[Not supported by viewer]
2
[Not supported by viewer]
3
[Not supported by viewer]
4
[Not supported by viewer] \ No newline at end of file +
$(USEMODULE)
$(USEPKG)
$(USEMODULE)...
Kconfig.dep
Kconfig.dep
out.config
out.config
menuconfig
menuconfig
autoconf.h
autoconf.h
0
0
1
1
2
2
3
3
4
4Viewer does not support full SVG 1.1 \ No newline at end of file