From ff916ca8674fd55b22445e39689abc285eaf8388 Mon Sep 17 00:00:00 2001 From: Jimmy Brisson Date: Wed, 21 Mar 2018 14:18:33 -0500 Subject: [PATCH 01/21] Overhaul the configuration system documentation --- docs/tools/config_system.md | 374 ++++++++++++++++-------------------- 1 file changed, 167 insertions(+), 207 deletions(-) diff --git a/docs/tools/config_system.md b/docs/tools/config_system.md index 6ac3c4bdd4..5fc5602f9c 100644 --- a/docs/tools/config_system.md +++ b/docs/tools/config_system.md @@ -1,23 +1,135 @@ ## The configuration system -The Arm Mbed configuration system customizes the compile time configuration of various Mbed components (targets, libraries and applications). Each component can define a number of *configuration parameters*. The values of these configuration parameters can then be *overridden* in various ways. Configuration is defined using [JSON](http://www.json.org/). Some examples of configuration parameters: +The Arm Mbed OS configuration system, a part of the Arm Mbed OS Build Tools, customizes compile time configuration parameters. Each library may define a number of configuration parameters in its `mbed_lib.json`. The values of these configuration parameters may be overridden by `mbed_app.json`. Configuration is defined using [JSON](http://www.json.org/). Some examples of configuration parameters: - The sampling period for a data acquisition application. - The default stack size for a newly created OS thread. - The receive buffer size of a serial communication library. - The flash and RAM memory size of an Mbed target. -The configuration system gathers and interprets all the configurations defined in the source tree. The output of the configuration system is a list of macros that are automatically defined when compiling the code. +The Arm Mbed OS configuration system gathers and interprets the configuration defined in the target, all `mbed_lib.json` files and the `mbed_app.json` file. The configuration system creates a single header file, `mbed_config.h`, that contains all of the defined configuration parameters converted into C preprocessor macros. `mbed compile` places `mbed_config.h` in the build directory and `mbed export` places it in the application root. The Arm Mbed OS configuration system is run during `mbed compile` before invoking the compiler and during `mbed export` before creating project files. -**Note:** In prior releases, the configuration system provided a method for adding custom targets. The Mbed OS tools now look for custom targets in a file named `custom_targets.json` in the root of a project and treat custom targets the same as [Mbed targets](/docs/development/tools/adding-and-configuring-targets.html). +**Note:** In prior releases, the configuration system provided a method for adding custom targets. The Mbed OS tools now look for custom targets in a file named `custom_targets.json` in the root of an application and treat custom targets the same as [Mbed targets](/docs/development/tools/adding-and-configuring-targets.html). + +### Examining available configuration parameters + +Mbed CLI includes a command for listing and explaining the compiliation time configuration, `mbed compile --config`. This command prints a summary of configuration parameters, such as: +``` +Configuration parameters +------------------------ +cellular.random_max_start_delay = 0 (macro name: "MBED_CONF_CELLULAR_RANDOM_MAX_START_DELAY") +cellular.use-apn-lookup = 1 (macro name: "MBED_CONF_CELLULAR_USE_APN_LOOKUP") +configuration-store.storage_disable = 0 (macro name: "CFSTORE_STORAGE_DISABLE") +drivers.uart-serial-rxbuf-size = 256 (macro name: "MBED_CONF_DRIVERS_UART_SERIAL_RXBUF_SIZE") +drivers.uart-serial-txbuf-size = 256 (macro name: "MBED_CONF_DRIVERS_UART_SERIAL_TXBUF_SIZE") +events.present = 1 (macro name: "MBED_CONF_EVENTS_PRESENT") +events.shared-dispatch-from-application = 0 (macro name: "MBED_CONF_EVENTS_SHARED_DISPATCH_FROM_APPLICATION") +events.shared-eventsize = 256 (macro name: "MBED_CONF_EVENTS_SHARED_EVENTSIZE") +events.shared-highprio-eventsize = 256 (macro name: "MBED_CONF_EVENTS_SHARED_HIGHPRIO_EVENTSIZE") +events.shared-highprio-stacksize = 1024 (macro name: "MBED_CONF_EVENTS_SHARED_HIGHPRIO_STACKSIZE") +events.shared-stacksize = 1024 (macro name: "MBED_CONF_EVENTS_SHARED_STACKSIZE") + +``` + +You may find that configuration naming does not always describe the parameter's purpose adequately. Include the `-v` switch to include the help text defined with the configuration parameter, where the value of the configuration parameter is defined, and other details. The command `mbed compile --config -v` in the same application as above prints: +``` +Configuration parameters +------------------------ +Name: cellular.random_max_start_delay + Description: Maximum random delay value used in start-up sequence in milliseconds + Defined by: library:cellular + No value set +Name: cellular.use-apn-lookup + Description: Use APN database lookup + Defined by: library:cellular + Macro name: MBED_CONF_CELLULAR_USE_APN_LOOKUP + Value: 1 (set by library:cellular) +Name: configuration-store.storage_disable + Description: Configuration parameter to disable flash storage if present. Default = 0, implying that by default flash storage is used if present. + Defined by: library:configuration-store + No value set + +``` + +### Using configuration data in code + +When compiling or exporting, the configuration system generates C preprocessor macro definitions of the configuration parameters. The configuration system writes these definitions in a file named `mbed_config.h` located in the build directory. When compiling the same example as the prior section for target `K64F`, the `mbed_config.h` file includes this snippet (note that the order of the definitions may be different): + +```C +// Automatically generated configuration file. +// DO NOT EDIT, content will be overwritten. + +#ifndef __MBED_CONFIG_DATA__ +#define __MBED_CONFIG_DATA__ + +// Configuration parameters +#define MBED_CONF_CELLULAR_RANDOM_MAX_START_DELAY 0 // set by library:cellular +#define MBED_CONF_CELLULAR_USE_APN_LOOKUP 1 // set by library:cellular + +``` + +**Note:** A macro definition will not be generated for a parameter that doesn't have a value. + + +The names of the macro for a configuration parameter is either a prefixed name or explicitly specified by `macro_name`. A prefixed name is constructed from the prefix `MBED_CONF_`, followed by the name of the library or `APP`, followed by the name of the parameter. The prefixed name is then capitalized and converted to a valid C macro name. For example, the `random_may_start_delay` configuration parameter in the library `cellular` is converted to `MBED_CONF_CELLULAR_RANDOM_MAX_START_DELAY`. + +The Mbed OS build tools instruct the compiler to process the file `mbed_config.h` as if it were the first include of any C or C++ source file, so you do not have to include `mbed_config.h` manually. + +Do not edit `mbed_config.h` manually. It may be overwritten the next time you compile or export your application, and all your changes will be lost. + +### Configuration parameters in `mbed_app.json`, `mbed_lib.json` + +An application may have one `mbed_app.json` in the root of the application and many `mbed_lib.json` files throughout the application. When present, `mbed_app.json` may override library and target configuration parameters and define new configuration parameters. + +#### Overriding configuration parameters + +The configuration system allows a user to override any defined configuration parameter with a JSON object named "target_overrides". + +The keys in the "target_overrides" section are the names of a target that the overrides apply to, or the special wildcard `*` that applies to all targets. The values within the "target_overrides" section are an object mapping configuration parameters, as printed by `mbed compile --conifg`, to new values. An example "target_overrides" section is provided below. + +```JSON +"target_overrides": { + "*": { + "cellular.random_max_start_delay": "100" + }, + "K64F": { + "cellular.use-apn-lookup": false + } +} +``` + +Examining the configuration for the target `LPC1768` with `mbed compile --config -m LPC1768` results in the following configuration: + +``` +Configuration parameters +------------------------ +cellular.random_max_start_delay = 100 (macro name: "MBED_CONF_CELLULAR_RANDOM_MAX_START_DELAY") +cellular.use-apn-lookup = 1 (macro name: "MBED_CONF_CELLULAR_USE_APN_LOOKUP") + +``` + +Examining the configuration for the target `K64F` with `mbed compile --config -m K64F` results in the following configuration: + +``` +Configuration parameters +------------------------ +cellular.random_max_start_delay = 100 (macro name: "MBED_CONF_CELLULAR_RANDOM_MAX_START_DELAY") +cellular.use-apn-lookup = 0 (macro name: "MBED_CONF_CELLULAR_USE_APN_LOOKUP") + +``` + +The order in which overrides are considered is: + + 1. Libraries override target configuration with `mbed_lib.json`. + 2. The application overrides target and library configuration with `mbed_app.json` #### Defining configuration parameters -The configuration system understands configuration data defined in targets, libraries and applications. Although there are some slight differences in the way the configuration system works in these cases, the configuration parameters are always defined in a JSON object called "config". +The configuration system understands configuration parameters defined in targets, libraries and applications. The configuration parameters are always defined in a JSON object called "config". For example: -``` +```JSON { "config": { "param1": { @@ -34,28 +146,40 @@ For example: } ``` -The JSON fragment above defines three configuration parameters named `param1`, `param2` and `param3`. There are two ways to define a configuration parameter: +You define a configuration parameter by specifying it's name as the key and specifying it's value either with a description object or by value. The JSON fragment above defines three configuration parameters named `param1`, `param2` and `param3`. -- *The short way:* by name and value. `param3` above is an example of a short definition for a parameter named `param3` with value `10`. -- *The long way:* by name and description (another JSON object), like `param1` and `param2` above. The JSON description object can have the following keys: - - `help`: an optional help message that describes the purpose of the parameter. - - `value`: an optional field that defines the value of the parameter. - - `required`: an optional key that specifies whether the parameter **must** be given a value before compiling the code (`false` by default). It's not possible to compile a source tree with one or more required parameters that don't have a value. Generally, it makes sense to define a required parameter only when it doesn't have a `value` key. - - `macro_name`: an optional name for the macro defined at compile time for this configuration parameter. The configuration system will automatically figure out the corresponding macro name for a configuration parameter, but the user can override this automatically computed name by specifying `macro_name`. +Above, the configuration parameters `param1` and `param2` are defined using a description object. The following keys are supported on the description object: + - `help`: an optional help message that describes the purpose of the parameter. + - `value`: an optional field that defines the value of the parameter. + - `required`: an optional key that specifies whether the parameter must be given a value before compiling the code (`false` by default). It's not possible to compile a source tree with one or more required parameters that don't have a value. Generally, setting `required` to true is only useful when `value` is not set. + - `macro_name`: an optional name for the macro defined at compile time for this configuration parameter. The configuration system will automatically figure out the corresponding macro name for a configuration parameter, but the user can override this automatically computed name by specifying `macro_name`. + +You define a macro by value by using an integer or string instead of the deception object, such as `param3` above. Defining a parameter by value is equivalent to a configuration parameter defined with a description object with the key `help` unset, the key `macro_name` unset, the key `required` set to `false`, and the key `value` set to the value in place of the description object. **Note:** the name of a parameter in `config` can't contain a dot (`.`) character. -The configuration system automatically appends an *implicit prefix* to the name of each parameter, so you don't have to worry about a name clash if you define a parameter with the same name in a library and a target, for example. The implicit prefix is: +The configuration system appends a prefix to the name of each parameter, so a parameter with the same name in a library does not conflict with parameters of the same name in targets or other libraries. The prefix is: -- **target.** if the parameter is defined in a target. -- **app.** if the parameter is defined in the application. -- The name of the library followed by a dot (.) if the parameter is defined in a library. +| Location | Prefix | +| -------- | ------ | +| target | `target.` | +| any library | The name of the library, as found in the `name` section of `mbed_lib.json`, followed by a dot (.) | +| application | `app.` | -#### Configuration data in libraries +### `mbed_lib.json` format specification -Each Mbed library can have an optional `mbed_lib.json` file located in the root folder of the library that defines its configuration. For a library called `mylib`, the configuration file can look like this: +`mbed_lib.json` is a JSON formatted document that contains a root JSON Object. The keys within this object are refered to as sections. The allowed sections and their meaning is listed below: -``` +| Section | Required | Meaning | +| ------- | -------- | ------- | +| `name` | Yes | name of the library. Must be unique. May not be `app` or `target`.| +| `macros` | No | List of macros to define on the command line. | +| `config` | No | Configuration parameters defined for use in this library. | +| `target_overrides` | No | Overrides for target configuration parameters and configuration parameters of the current library. | + +The following is an example library, "mylib". + +```JSON { "name": "mylib", "config": { @@ -78,7 +202,8 @@ Each Mbed library can have an optional `mbed_lib.json` file located in the root }, "NXP": { "queue_size": 20, - "buffer_size": 128 + "buffer_size": 128, + "target.features_add": ["IPV4"] } } } @@ -88,90 +213,33 @@ In this JSON file: - `name` is the name of the library. **This is a required field.** - `config` defines the configuration parameters of the library, as explained in the section about [defining configuration parameters](#defining-configuration-parameters). -- `macros` is a list of extra macros that will be defined when compiling a project that includes this library. A macro can be defined without a value (such as `MYMOD_MACRO1` above) or with a value (such as `MYMOD_MACRO2` above). +- `macros` is a list of extra macros that will be defined when compiling a application that includes this library. A macro can be defined without a value (such as `MYMOD_MACRO1` above) or with a value (such as `MYMOD_MACRO2` above). - `target_overrides` is a dictionary with target-specific values for the configuration parameters. -`target_overrides` is used to override the values of the parameters depending on the current compilation target. The keys in `target_overrides` are matched against toolchain *labels*. (You can find a description of Mbed targets in our documentation about [adding and configuring targets](/docs/development/tools/adding-and-configuring-targets.html).) If a key inside `target_overrides` matches one of the target labels, the parameter values are changed according to the value of the key. In the example above: +All configuration parameters defined in `mylib` have a `mylib.` prefix. In a `mbed_app.json`, `buffer_size` is accessible using the name `mylib.buffer_size`. +`target_overrides` is used to override the values of the parameters depending on the current compilation target. The keys in `target_overrides` are matched against target labels. (You can find a description of Mbed targets in our documentation about [adding and configuring targets](/docs/development/tools/adding-and-configuring-targets.html).) If a key inside `target_overrides` matches one of the target labels, the parameter values are changed according to the value of the key. -- `config` is always processed first, independent of the target. `config` might define values for some of the parameters. In this case, `buffer_size` will be set to 1024, `queue_size` will be set to 10 and `timer_period` will not have a value. -- If the library is compiled for the `K64F` target, `timer_period` will be set to 100, and `queue_size` will be set to 40 because they are overridden by the `K64F` key in `target_overrides`. `buffer_size` will be set to 1024, as defined in `config`. -- Assuming that `NXP` is a label defined by **all** NXP based targets, if the library is compiled for **any** `NXP` target (like `LPC1768` or `LPC11U24`), `buffer_size` will be set to 128 and `queue_size` will be set to 20, while `timer_period` will not have a value (since it doesn't get one either in `config` or in the `NXP` override). -- The keys in `target_overrides` are processed in order: if a hypothetical target defines both `K64F` and `NXP` as labels, `timer_period` will be set to 100, `queue_size` will be set to 20 and `buffer_size` will be set to 128. -- If the library is compiled for a target that doesn't have `K64F` or `NXP` as labels, the values of the parameters will be the ones set in `config`. +It is an error for `mbed_lib.json` to override configuration parameters that were not defined. -Except `name`, all the above keys in the JSON file are optional. However, if `target_overrides` is defined, `config` must also be defined. +#### Overriding target attributes -As explained in the section about [defining configuration parameters](#defining-configuration-parameters), the parameters have an implicit `mylib.` prefix. Outside `mylib`, `buffer_size` is accessible using the name `mylib.buffer_size`. An application will be able to override the value of this parameter, as described in [this section](#configuration-data-in-applications). +Target configurations contain a set of attributes that you may manipulate with configuration. You may override these attributes as if they were a normal configuration parameter. If these attributes are cumulative, you may also manipulate them with the special `attribute_add` and `attribute_remove` attributes. Find a list of the attributes that may be overwritten in our documentation about [adding and configuring targets](/docs/development/tools/adding-and-configuring-targets.html) -If the source tree has code for more than one library, each library needs its own `mbed_lib.json` file in its root folder. -##### Configuration data in targets +### `mbed_app.json` Specification -Like libraries, targets can define their own configuration data. Additionally, targets can override the configuration of the target(s) they inherit from (for more details about how do define a target and target inheritance, check [our configuring targets documentation](/docs/development/tools/adding-and-configuring-targets.html)). Target configuration data is defined in `targets.json` using `config`, as described in the section about [defining configuration parameters](#defining-configuration-parameters). An example for a hypothetical `Base` target is given below: +`mbed_app.json` may be present at the root of your application or specified as the argument to the `--app-config` parameter. Unlike library configuration, only one `mbed_app.json` is interpreted during `mbed compile` or `mbed export`. like `mbed_lib.json`, `mbed_app.json` is a JSON formatted document that contains a root JSON Object. The keys within this object are refered to as sections. The allowed sections and their meaning is listed below: -``` -"Base": { - "core": "Cortex-M0", - "extra_labels": ["BASE_LABEL"], - "config": { - "serial_console_speed": { - "help": "Baud rate of the serial console", - "value": 115200, - "macro_name": "MBED_SERIAL_UART_SPEED" - }, - "stack_size": { - "help": "Initial stack size of the application", - "value": 128 - } - } -} -``` - -Like library parameters, target-defined parameters have an implicit prefix. For a target, the prefix is always called `target` (no matter what the actual target name is), so the above configuration parameters will be accessible outside the definition in `Base` (and any other target) as `target.serial_console_speed` and `target.stack_size`. +| Section | Required | Meaning | +| ------- | -------- | ------- | +| `artifact_name` | No | The name for the executable to generate. Defaults to the name of the containing directory. | +| `macros` | No | List of macros to define on the command line. | +| `config` | No | Configuration parameters defined for use in this library. | +| `target_overrides` | No | Overrides for target, library and application configuration parameters. | -Targets can inherit from other targets, and their configuration data is also inherited. A target that inherits from one or more other targets can add new parameters in its own `config` section and can also override the configuration parameters defined by its parent(s) in the `overrides` section. For example: +The application can freely override the configuration of any of the libraries it depends on, as well as the configuration data in targets, so it has complete control over the configuration of the whole build. For example, an `mbed_app.json` from an application that depends on `mylib` above may look like this: -``` -"Derived": { - "inherits": ["Base"], - "extra_labels_add": ["NXP"], - "config": { - "my_own_config": { - "help": "My very own configuration parameter", - "value": 0 - } - }, - "overrides": { - "stack_size": 256 - } -} -``` - -`Derived` above defines its own configuration parameter called `my_own_config` and inherits the configuration parameters from `Base`, so its configuration parameters are `serial_console_speed`, `stack_size` and `my_own_config`. It also overrides the value of the `stack_size` parameter defined in `Base`. This means that: - -- When compiling for `Base`, the target will define two configuration parameters: `serial_console_speed` with the value 115200 and `stack_size` with the value 128. -- When compiling for `Derived`, the target will define three configuration parameters: `serial_console_speed` with the value 115200, `stack_size` with the value 256 and `my_own_config` with the value 0. - -It is an error for a derived target to redefine a configuration parameter already defined by its parent(s) in its `config` section. It is also an error for a derived target to override a configuration parameter that was not defined by its parent(s) in its `overrides` section. - -#### Configuration data in applications - -Like target and library configuration, application configuration is optional; if it exists, it must be defined in an `mbed_app.json` file. Unlike library configuration, there can be a single `mbed_app.json` file in the source tree. - -There are similarities between configuration data in applications and libraries: - -- Applications define their configuration parameters in the `config` section of `mbed_app.json`, as explained [in the section](#defining-configuration-parameters) about defining parameters. -- Applications can specify target-dependent values in their `target_overrides` section, as described in the [library configuration paragraph](#configuration-data-in-libraries) (but see below for differences). -- Applications can define macros that will be defined at compile time by declaring them in `macros`. - -There are also a few differences: - -- Applications **can't** have a `name` key in `mbed_app.json`. The prefix for the configuration parameters defined in an application is always `app.`. -- Applications can also override library and target configurations, in addition to their own configuration, in their `target_overrides` section. - -The last point above is important. The application can freely override the configuration of any of the libraries it depends on, as well as the configuration data in targets, so it has complete control over the configuration of the whole build. For an application called ``myapp`` that depends on ``mylib`` above, the configuration can look like this: - -``` +```JSON { "config": { "welcome_string": { @@ -181,128 +249,20 @@ The last point above is important. The application can freely override the confi }, "target_overrides": { "*": { - "target.serial_console_speed": 2400, "mylib.timer_period": 100 }, - "Base": { - "target.serial_console_speed": 9600 + "NCS36510": { + "target.mac_addr_high": "0x11223344" } } } ``` -`target_overrides` works a lot like it does in libraries, but there are a few differences: - -- Because the application can override any configuration parameter, it must specify configuratoin parameters using their prefix (like `mylib.timer_period`). If an overridden parameter doesn't have a prefix, the config system assumes that the overridden paramater is one of the parameters the application defines in its own `config` section. -- The `*` key in `target_overrides` will match *any* target. It is possible to use the `*` key in a library's `target_overrides` too, but it'd make little sense to do so, since it will always override the values defined in the library's `config` section. In an application it might make sense to use the `*` key, since it can be used to override the configuration defined by the target or the dependent libraries, no matter which target is used for building. +The application may override any configuration parameter by specifying the configuration parameters including their prefix (like `mylib.timer_period`). If an overridden parameter doesn't have a prefix, it overrides a parameter in its own `config` section. -Other than this, `target_overrides` works exactly like it does for libraries. Keys in `target_overrides` are still processed in the order they are defined, so for the example above, the `*` override is always processed first (because it matches all targets) and then `Base` is only processed for the `Base` target. +`myapp` above defines its own configuration parameter (`welcome_string`) and overrides the configuration in both the target (`target.mac_addr_high`) and its `mylib` dependency (`mylib.timer_period`): -`myapp` above defines its own configuration parameter (`welcome_string`) and overrides the configuration in both the target (`target.serial_console_speed`) and its `mylib` dependency (`mylib.timer_period`): - -- When compiling for `Base`, `app.welcome_string` is `"Hello!"`, `target.serial_console_speed` is 9600 (from the `Base` override) and `mylib.timer_period` is 100 (from the `*` override). -- When compiling for `Derived`, `app.welcome_string` is `"Hello!"`, `target.serial_console_speed` is 2400 (from the `*` override) and `mylib.timer_period` is 100 (also from the `*` override). +- When compiling for `NCS36510`, `app.welcome_string` is `"Hello!"`, `target.mac_addr_high` is `"0x11223344"` (from the `NCS36510` override) and `mylib.timer_period` is 100 (from the `*` override). +- When compiling for `LPC1768`, `app.welcome_string` is `"Hello!"` and `mylib.timer_period` is 100 (also from the `*` override). It is an error for the application configuration to override configuration parameters that were not defined. - -##### Overriding target attributes - -Target configurations contain a set of attributes that you may manipulate with an application configuration. You may override these attributes as if they were a normal configuration parameter. If these attributes are cumulative, you may also manipulate them with the special `attribute_add` and `attribute_remove` meta-attributes. - -Cumulative attributes: - -- `features`: This attribute contains a list of features that the Mbed OS tools compile into the resulting binary and are available at runtime. The Mbed OS tools include all code within a directory whose name is an entry of the `features` attribute prefixed with `FEATURE_`. Further, the Mbed OS tools emit all entries within this attribute as macros prefixed with `FEATURE_`. If two different libraries try to add and remove the same feature, the Mbed OS tools will report an error. -- `device_has`: This attribute is a list of hardware components available on the target. The Mbed OS tools emit all entries within this attribute as macros prefixed with `DEVICE_`. -- `extra_labels`: The `extra_labels` attribute is a list of labels that the Mbed OS tools use to include code. The Mbed OS tools include all code within a directory whose name is an entry of the `extra_labels` attribute prefixed with `TARGET_`. The Mbed OS tools also emit all entries in this attribute as macros prefixed with `TARGET_`. -- `macros`: This attribute is a list of target-specific macros that the Mbed OS tools define during compilation. - -For example, this `mbed_app.json` disables the IPV4 feature; using this network stack will result in a compilation error: - -``` -{ - "target_overrides": { - "K64F": { - "target.features_remove": ["IPV4"] - } - } -} -``` - -#### Configuration data precedence - -The order in which the various bits of configurations are considered is: - -- The configuration defined by an inherited target overrides the configuration defined by its parent(s), as described [above](#configuration-data-in-targets). -- The configuration of the top level application overrides the configuration defined by the target and any of the libraries on which it depends. - -For `myapp` above: - -- The value of `target.serial_console_speed` is: - - 9600 when compiling for `Base` because of the `Base` override in myapp's `target_overrides`. - - 2400 when compiling for any other target because of the `*` override in myapp's `target_overrides`. -- The value of `target.stack_size` is: - - 256 when compiling for `Derived`. - - 128 when compiling for `Base` - or any other target that derives from `Base` (assuming that `Derived` is the only target that redefines `stack_size`). -- The value of `mylib.timer_period` is 100 because that's overridden by the application and takes precedence over the values defined in `mylib`. -- The values of `mylib.buffer_size` and `mylib.queue_size` are: - - 1024 and 10, respectively, when compiling for `Base`, as defined in the `config` section of `mylib`. - - 128 and 20, respectively, because `Derived` defines the `NXP` label and `mylib` defines a specific configuration for this label. -- Because `Derived` has its own `my_own_config` configuration parameter, `target.my_own_config` will also be defined in this case. - -#### Using configuration data in the code - -When compiling, the configuration system will automatically generate macro definitions for the configuration parameters and all the macros defined in libraries and the application in their `macros` keys. These definitions will be written in a file named `mbed_config.h`, located in the build directory. When compiling `myapp` for target `Base`, the `mbed_config.h` file will look like this (note that the order of the definitions may be different): - -``` -// Automatically generated configuration file. -// DO NOT EDIT, content will be overwritten. - -#ifndef __MBED_CONFIG_DATA__ -#define __MBED_CONFIG_DATA__ - -// Configuration parameters -#define MBED_CONF_MYAPP_WELCOME_STRING "Hello!" // set by application -#define MBED_SERIAL_UART_SPEED 9600 // set by application[Base] -#define MBED_CONF_TARGET_STACK_SIZE 128 // set by target -#define INTERNAL_GPTMR_PERIOD 100 // set by application[*] -#define MBED_CONF_MYLIB_BUFFER_SIZE 1024 // set by library:mylib -#define MBED_CONF_MYLIB_QUEUE_SIZE 10 // set by library:mylib -// Macros -#define MYMOD_MACRO1 // defined by library:mylib -#define MYMOD_MACRO2 "TEST" // defined by library:mylib - -#endif -``` - -When compiling for `Derived`, `mbed_config.h` will look like this: - - -``` -// Automatically generated configuration file. -// DO NOT EDIT, content will be overwritten. - -#ifndef __MBED_CONFIG_DATA__ -#define __MBED_CONFIG_DATA__ - -// Configuration parameters -#define MBED_CONF_MYAPP_WELCOME_STRING "Hello!" // set by application -#define MBED_SERIAL_UART_SPEED 2400 // set by application[*] -#define MBED_CONF_TARGET_STACK_SIZE 256 // set by target -#define MBED_CONF_TARGET_MY_OWN_CONFIG 0 // set by target -#define INTERNAL_GPTMR_PERIOD 100 // set by application[*] -#define MBED_CONF_MYLIB_BUFFER_SIZE 128 // set by library:mylib[NXP] -#define MBED_CONF_MYLIB_QUEUE_SIZE 20 // set by library:mylib[NXP] -// Macros -#define MYMOD_MACRO1 // defined by library:mylib -#define MYMOD_MACRO2 "TEST" // defined by library:mylib - -#endif -``` - -Note that a macro definition will *not* be generated for a parameter that doesn't have a value. - -The names of the macros for the configuration parameter (unless explicitly specified by `macro_name`) are prefixed by **MBED_CONF_**, followed by the full (prefixed) name of the parameter, capitalized and converted to a valid C macro name (if needed). - -`mbed_config.h` will be included automatically by the toolchain in all compiled sources, so you'll have access to the configuration data without having to include `mbed_config.h` manually. - -*Do not `edit mbed_config.h manually`*. It will be overwritten the next time you compile or export your project, and all your changes will be lost. From 0f73b53e6622563b5431c2ea5985b06c96bb3c39 Mon Sep 17 00:00:00 2001 From: Brendan McDonnell Date: Wed, 21 Mar 2018 21:55:41 -0400 Subject: [PATCH 02/21] minor typo/grammar/etc. fixes, and recommended rephrasings --- docs/tools/config_system.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/tools/config_system.md b/docs/tools/config_system.md index 5fc5602f9c..a65a59a85f 100644 --- a/docs/tools/config_system.md +++ b/docs/tools/config_system.md @@ -7,13 +7,13 @@ The Arm Mbed OS configuration system, a part of the Arm Mbed OS Build Tools, cus - The receive buffer size of a serial communication library. - The flash and RAM memory size of an Mbed target. -The Arm Mbed OS configuration system gathers and interprets the configuration defined in the target, all `mbed_lib.json` files and the `mbed_app.json` file. The configuration system creates a single header file, `mbed_config.h`, that contains all of the defined configuration parameters converted into C preprocessor macros. `mbed compile` places `mbed_config.h` in the build directory and `mbed export` places it in the application root. The Arm Mbed OS configuration system is run during `mbed compile` before invoking the compiler and during `mbed export` before creating project files. +The configuration system gathers and interprets the configuration defined in the target, all `mbed_lib.json` files and the `mbed_app.json` file. It creates a single header file, `mbed_config.h`, that contains all of the defined configuration parameters converted into C preprocessor macros. `mbed compile` places `mbed_config.h` in the build directory; `mbed export` places it in the application root. The configuration system is run during `mbed compile` before invoking the compiler and during `mbed export`, before creating project files. **Note:** In prior releases, the configuration system provided a method for adding custom targets. The Mbed OS tools now look for custom targets in a file named `custom_targets.json` in the root of an application and treat custom targets the same as [Mbed targets](/docs/development/tools/adding-and-configuring-targets.html). ### Examining available configuration parameters -Mbed CLI includes a command for listing and explaining the compiliation time configuration, `mbed compile --config`. This command prints a summary of configuration parameters, such as: +Mbed CLI includes a command for listing and explaining the compile time configuration, `mbed compile --config`. This command prints a summary of configuration parameters, such as: ``` Configuration parameters ------------------------ @@ -71,7 +71,7 @@ When compiling or exporting, the configuration system generates C preprocessor m **Note:** A macro definition will not be generated for a parameter that doesn't have a value. -The names of the macro for a configuration parameter is either a prefixed name or explicitly specified by `macro_name`. A prefixed name is constructed from the prefix `MBED_CONF_`, followed by the name of the library or `APP`, followed by the name of the parameter. The prefixed name is then capitalized and converted to a valid C macro name. For example, the `random_may_start_delay` configuration parameter in the library `cellular` is converted to `MBED_CONF_CELLULAR_RANDOM_MAX_START_DELAY`. +The name of the macro for a configuration parameter is either a prefixed name or explicitly specified by `macro_name`. A prefixed name is constructed from the prefix `MBED_CONF_`, followed by the name of the library or `APP`, followed by the name of the parameter. The prefixed name is then capitalized and converted to a valid C macro name. For example, the `random_may_start_delay` configuration parameter in the library `cellular` is converted to `MBED_CONF_CELLULAR_RANDOM_MAX_START_DELAY`. The Mbed OS build tools instruct the compiler to process the file `mbed_config.h` as if it were the first include of any C or C++ source file, so you do not have to include `mbed_config.h` manually. @@ -83,9 +83,9 @@ An application may have one `mbed_app.json` in the root of the application and m #### Overriding configuration parameters -The configuration system allows a user to override any defined configuration parameter with a JSON object named "target_overrides". +The configuration system allows a user to override any defined configuration parameter with a JSON object named `"target_overrides"`. -The keys in the "target_overrides" section are the names of a target that the overrides apply to, or the special wildcard `*` that applies to all targets. The values within the "target_overrides" section are an object mapping configuration parameters, as printed by `mbed compile --conifg`, to new values. An example "target_overrides" section is provided below. +The keys in the `"target_overrides"` section are the names of a target that the overrides apply to, or the special wildcard `*` that applies to all targets. The values within the `"target_overrides"` section are an object mapping configuration parameters, as printed by `mbed compile --conifg`, to new values. An example `"target_overrides"` section is provided below. ```JSON "target_overrides": { @@ -146,7 +146,7 @@ For example: } ``` -You define a configuration parameter by specifying it's name as the key and specifying it's value either with a description object or by value. The JSON fragment above defines three configuration parameters named `param1`, `param2` and `param3`. +You define a configuration parameter by specifying its name as the key and specifying its value either with a description object or by value. The JSON fragment above defines three configuration parameters named `param1`, `param2` and `param3`. Above, the configuration parameters `param1` and `param2` are defined using a description object. The following keys are supported on the description object: - `help`: an optional help message that describes the purpose of the parameter. @@ -154,9 +154,9 @@ Above, the configuration parameters `param1` and `param2` are defined using a de - `required`: an optional key that specifies whether the parameter must be given a value before compiling the code (`false` by default). It's not possible to compile a source tree with one or more required parameters that don't have a value. Generally, setting `required` to true is only useful when `value` is not set. - `macro_name`: an optional name for the macro defined at compile time for this configuration parameter. The configuration system will automatically figure out the corresponding macro name for a configuration parameter, but the user can override this automatically computed name by specifying `macro_name`. -You define a macro by value by using an integer or string instead of the deception object, such as `param3` above. Defining a parameter by value is equivalent to a configuration parameter defined with a description object with the key `help` unset, the key `macro_name` unset, the key `required` set to `false`, and the key `value` set to the value in place of the description object. +You define a macro by value by using an integer or string instead of the description object, such as `param3` above. Defining a parameter by value is equivalent to a configuration parameter defined with a description object with the key `value` set to the value in place of the description object, the key `help` unset, the key `macro_name` unset, and the key `required` set to `false`. -**Note:** the name of a parameter in `config` can't contain a dot (`.`) character. +**Note:** The name of a parameter in `config` can't contain a dot (`.`) character. The configuration system appends a prefix to the name of each parameter, so a parameter with the same name in a library does not conflict with parameters of the same name in targets or other libraries. The prefix is: @@ -228,7 +228,7 @@ Target configurations contain a set of attributes that you may manipulate with c ### `mbed_app.json` Specification -`mbed_app.json` may be present at the root of your application or specified as the argument to the `--app-config` parameter. Unlike library configuration, only one `mbed_app.json` is interpreted during `mbed compile` or `mbed export`. like `mbed_lib.json`, `mbed_app.json` is a JSON formatted document that contains a root JSON Object. The keys within this object are refered to as sections. The allowed sections and their meaning is listed below: +`mbed_app.json` may be present at the root of your application or specified as the argument to the `--app-config` parameter. Unlike library configuration, only one `mbed_app.json` is interpreted during `mbed compile` or `mbed export`. Like `mbed_lib.json`, `mbed_app.json` is a JSON formatted document that contains a root JSON Object. The keys within this object are refered to as sections. The allowed sections and their meaning is listed below: | Section | Required | Meaning | | ------- | -------- | ------- | From bf1062fc9ba4e0639db935a5700efe707ddb1a2c Mon Sep 17 00:00:00 2001 From: Jimmy Brisson Date: Thu, 22 Mar 2018 08:56:53 -0500 Subject: [PATCH 03/21] Remove outdated, incorrect note --- docs/tools/config_system.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/tools/config_system.md b/docs/tools/config_system.md index 5fc5602f9c..96f4ffd3ac 100644 --- a/docs/tools/config_system.md +++ b/docs/tools/config_system.md @@ -68,9 +68,6 @@ When compiling or exporting, the configuration system generates C preprocessor m ``` -**Note:** A macro definition will not be generated for a parameter that doesn't have a value. - - The names of the macro for a configuration parameter is either a prefixed name or explicitly specified by `macro_name`. A prefixed name is constructed from the prefix `MBED_CONF_`, followed by the name of the library or `APP`, followed by the name of the parameter. The prefixed name is then capitalized and converted to a valid C macro name. For example, the `random_may_start_delay` configuration parameter in the library `cellular` is converted to `MBED_CONF_CELLULAR_RANDOM_MAX_START_DELAY`. The Mbed OS build tools instruct the compiler to process the file `mbed_config.h` as if it were the first include of any C or C++ source file, so you do not have to include `mbed_config.h` manually. From c24ba3800216cba2b939828b8f17fdaf289e9df3 Mon Sep 17 00:00:00 2001 From: Jimmy Brisson Date: Thu, 22 Mar 2018 08:59:58 -0500 Subject: [PATCH 04/21] Reword intro to config params should avoid confusion about "target configuration parameters" --- docs/tools/config_system.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tools/config_system.md b/docs/tools/config_system.md index 96f4ffd3ac..79c1f26a1d 100644 --- a/docs/tools/config_system.md +++ b/docs/tools/config_system.md @@ -76,7 +76,7 @@ Do not edit `mbed_config.h` manually. It may be overwritten the next time you co ### Configuration parameters in `mbed_app.json`, `mbed_lib.json` -An application may have one `mbed_app.json` in the root of the application and many `mbed_lib.json` files throughout the application. When present, `mbed_app.json` may override library and target configuration parameters and define new configuration parameters. +An application may have one `mbed_app.json` in the root of the application and many `mbed_lib.json` files throughout the application. When present, `mbed_app.json` may override configuration parameters defined in libraries and the target and define new configuration parameters. #### Overriding configuration parameters From edbb0ba74a3d90fe4125340a390fdc0897f20b38 Mon Sep 17 00:00:00 2001 From: Jimmy Brisson Date: Thu, 22 Mar 2018 09:06:19 -0500 Subject: [PATCH 05/21] Clarify first use of "config in target" --- docs/tools/config_system.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tools/config_system.md b/docs/tools/config_system.md index 79c1f26a1d..5b19d2e754 100644 --- a/docs/tools/config_system.md +++ b/docs/tools/config_system.md @@ -7,7 +7,7 @@ The Arm Mbed OS configuration system, a part of the Arm Mbed OS Build Tools, cus - The receive buffer size of a serial communication library. - The flash and RAM memory size of an Mbed target. -The Arm Mbed OS configuration system gathers and interprets the configuration defined in the target, all `mbed_lib.json` files and the `mbed_app.json` file. The configuration system creates a single header file, `mbed_config.h`, that contains all of the defined configuration parameters converted into C preprocessor macros. `mbed compile` places `mbed_config.h` in the build directory and `mbed export` places it in the application root. The Arm Mbed OS configuration system is run during `mbed compile` before invoking the compiler and during `mbed export` before creating project files. +The Arm Mbed OS configuration system gathers and interprets the configuration defined in the target in its [target configuration](/docs/development/tools/adding-and-configuring-targets.html), all `mbed_lib.json` files and the `mbed_app.json` file. The configuration system creates a single header file, `mbed_config.h`, that contains all of the defined configuration parameters converted into C preprocessor macros. `mbed compile` places `mbed_config.h` in the build directory and `mbed export` places it in the application root. The Arm Mbed OS configuration system is run during `mbed compile` before invoking the compiler and during `mbed export` before creating project files. **Note:** In prior releases, the configuration system provided a method for adding custom targets. The Mbed OS tools now look for custom targets in a file named `custom_targets.json` in the root of an application and treat custom targets the same as [Mbed targets](/docs/development/tools/adding-and-configuring-targets.html). From 92c47d3a26cc2446cb48c942fceca150da82839e Mon Sep 17 00:00:00 2001 From: Jimmy Brisson Date: Thu, 22 Mar 2018 09:06:42 -0500 Subject: [PATCH 06/21] Add note about library definition --- docs/tools/config_system.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/tools/config_system.md b/docs/tools/config_system.md index 5b19d2e754..c894d81a7a 100644 --- a/docs/tools/config_system.md +++ b/docs/tools/config_system.md @@ -9,6 +9,8 @@ The Arm Mbed OS configuration system, a part of the Arm Mbed OS Build Tools, cus The Arm Mbed OS configuration system gathers and interprets the configuration defined in the target in its [target configuration](/docs/development/tools/adding-and-configuring-targets.html), all `mbed_lib.json` files and the `mbed_app.json` file. The configuration system creates a single header file, `mbed_config.h`, that contains all of the defined configuration parameters converted into C preprocessor macros. `mbed compile` places `mbed_config.h` in the build directory and `mbed export` places it in the application root. The Arm Mbed OS configuration system is run during `mbed compile` before invoking the compiler and during `mbed export` before creating project files. +**Note:** Throughout this document, library mean any reusable piece of code within its own directory. + **Note:** In prior releases, the configuration system provided a method for adding custom targets. The Mbed OS tools now look for custom targets in a file named `custom_targets.json` in the root of an application and treat custom targets the same as [Mbed targets](/docs/development/tools/adding-and-configuring-targets.html). ### Examining available configuration parameters From a12978deca392e793f5af9f315771f222e480670 Mon Sep 17 00:00:00 2001 From: Jimmy Brisson Date: Thu, 22 Mar 2018 09:13:19 -0500 Subject: [PATCH 07/21] Reword cumulative attributes to be more specific --- docs/tools/config_system.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tools/config_system.md b/docs/tools/config_system.md index c894d81a7a..15a28da6cc 100644 --- a/docs/tools/config_system.md +++ b/docs/tools/config_system.md @@ -222,7 +222,7 @@ It is an error for `mbed_lib.json` to override configuration parameters that wer #### Overriding target attributes -Target configurations contain a set of attributes that you may manipulate with configuration. You may override these attributes as if they were a normal configuration parameter. If these attributes are cumulative, you may also manipulate them with the special `attribute_add` and `attribute_remove` attributes. Find a list of the attributes that may be overwritten in our documentation about [adding and configuring targets](/docs/development/tools/adding-and-configuring-targets.html) +Target configurations contain a set of attributes that you may manipulate with configuration. You may override these attributes as if they were a normal configuration parameter. If these attributes are cumulative, they are a list of items that you may add to with the special attribute `attribute_add` and subtract from with `attribute_remove`. It is an error to both add and subtract the same value from a cumulative attribute. Find a list of the attributes that may be overwritten in our documentation about [adding and configuring targets](/docs/development/tools/adding-and-configuring-targets.html) ### `mbed_app.json` Specification From 6c2cb40a3330b83bb7ef474bf76646e7814ff078 Mon Sep 17 00:00:00 2001 From: Jimmy Brisson Date: Thu, 22 Mar 2018 09:14:09 -0500 Subject: [PATCH 08/21] Remove undefined "myapp" --- docs/tools/config_system.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tools/config_system.md b/docs/tools/config_system.md index 15a28da6cc..2b1a6608de 100644 --- a/docs/tools/config_system.md +++ b/docs/tools/config_system.md @@ -259,7 +259,7 @@ The application can freely override the configuration of any of the libraries it The application may override any configuration parameter by specifying the configuration parameters including their prefix (like `mylib.timer_period`). If an overridden parameter doesn't have a prefix, it overrides a parameter in its own `config` section. -`myapp` above defines its own configuration parameter (`welcome_string`) and overrides the configuration in both the target (`target.mac_addr_high`) and its `mylib` dependency (`mylib.timer_period`): +The `mbed_app.json` above defines its own configuration parameter (`welcome_string`) and overrides the configuration in both the target (`target.mac_addr_high`) and its `mylib` dependency (`mylib.timer_period`): - When compiling for `NCS36510`, `app.welcome_string` is `"Hello!"`, `target.mac_addr_high` is `"0x11223344"` (from the `NCS36510` override) and `mylib.timer_period` is 100 (from the `*` override). - When compiling for `LPC1768`, `app.welcome_string` is `"Hello!"` and `mylib.timer_period` is 100 (also from the `*` override). From c1c24aa29564d7ea82c57c79b7eabf035bfce2f3 Mon Sep 17 00:00:00 2001 From: Jimmy Brisson Date: Thu, 22 Mar 2018 09:24:38 -0500 Subject: [PATCH 09/21] Typo correction --- docs/tools/config_system.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tools/config_system.md b/docs/tools/config_system.md index 29e51c5f9f..b6a51083e6 100644 --- a/docs/tools/config_system.md +++ b/docs/tools/config_system.md @@ -71,7 +71,7 @@ When compiling or exporting, the configuration system generates C preprocessor m ``` -The name of the macro for a configuration parameter is either a prefixed name or explicitly specified by `macro_name`. A prefixed name is constructed from the prefix `MBED_CONF_`, followed by the name of the library or `APP`, followed by the name of the parameter. The prefixed name is then capitalized and converted to a valid C macro name. For example, the `random_may_start_delay` configuration parameter in the library `cellular` is converted to `MBED_CONF_CELLULAR_RANDOM_MAX_START_DELAY`. +The name of the macro for a configuration parameter is either a prefixed name or explicitly specified by `macro_name`. A prefixed name is constructed from the prefix `MBED_CONF_`, followed by the name of the library or `APP`, followed by the name of the parameter. The prefixed name is then capitalized and converted to a valid C macro name. For example, the `random_max_start_delay` configuration parameter in the library `cellular` is converted to `MBED_CONF_CELLULAR_RANDOM_MAX_START_DELAY`. The Mbed OS build tools instruct the compiler to process the file `mbed_config.h` as if it were the first include of any C or C++ source file, so you do not have to include `mbed_config.h` manually. From e007fe8c6a3ee871418c8e6fd2baec3d32fe8565 Mon Sep 17 00:00:00 2001 From: Jimmy Brisson Date: Thu, 22 Mar 2018 09:30:04 -0500 Subject: [PATCH 10/21] Expand on cumulative attributes --- docs/tools/config_system.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/tools/config_system.md b/docs/tools/config_system.md index b6a51083e6..7d0f362c64 100644 --- a/docs/tools/config_system.md +++ b/docs/tools/config_system.md @@ -223,7 +223,13 @@ It is an error for `mbed_lib.json` to override configuration parameters that wer #### Overriding target attributes -Target configurations contain a set of attributes that you may manipulate with configuration. You may override these attributes as if they were a normal configuration parameter. If these attributes are cumulative, they are a list of items that you may add to with the special attribute `attribute_add` and subtract from with `attribute_remove`. It is an error to both add and subtract the same value from a cumulative attribute. Find a list of the attributes that may be overwritten in our documentation about [adding and configuring targets](/docs/development/tools/adding-and-configuring-targets.html) +Target configurations contain a set of attributes that you may manipulate with configuration. You may override these attributes as if they were a normal configuration parameter. Attributes may be cumulative, in which case they are a list of items. You may add to a cumulative attribute by overriding a configuration parameter with the name of the cumulative attribute suffixed with `_add` and remove from a cumulative attribute with the suffix `_remove`. When overriding, adding or subtracting from a cumulative attribute, the value must be a list of items to replace the definition with, add or remove. For example, you add the value `IPV4` to a target's features list with the syntax: + +```JSON +"target.features_add": ["IPV4"] +``` + +It is an error to both add and subtract the same value from a cumulative attribute. Find a list of the attributes that may be overwritten in our documentation about [adding and configuring targets](/docs/development/tools/adding-and-configuring-targets.html) ### `mbed_app.json` Specification From 2e93c6d52a22eb5684f556016dc57c80fb5f2448 Mon Sep 17 00:00:00 2001 From: Jimmy Brisson Date: Thu, 22 Mar 2018 09:35:36 -0500 Subject: [PATCH 11/21] Reword individual config sections to mention how they were generated --- docs/reference/configuration/Connectivity.md | 2 +- docs/reference/configuration/Drivers.md | 1 + docs/reference/configuration/Platform.md | 2 ++ docs/reference/configuration/RTOS.md | 3 +++ 4 files changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/reference/configuration/Connectivity.md b/docs/reference/configuration/Connectivity.md index 87a46cadca..d5277264fa 100644 --- a/docs/reference/configuration/Connectivity.md +++ b/docs/reference/configuration/Connectivity.md @@ -1,7 +1,7 @@

Connectivity

-You can configure various parameters using either C++ APIs or the Arm Mbed configuration system. Below are the parameters you can configure using the Mbed configuration system: +You can configure various parameters using either C++ APIs or the Arm Mbed configuration system. The following is the complete list of Connectivity configuration parameters, as generated by `mbed compile --config -v`. Please see [the Configuration system documentation](/docs/tools/config_system.md) for details on how you may use or override these settings. ``` Configuration parameters diff --git a/docs/reference/configuration/Drivers.md b/docs/reference/configuration/Drivers.md index 9c1527450d..683659385b 100644 --- a/docs/reference/configuration/Drivers.md +++ b/docs/reference/configuration/Drivers.md @@ -1,5 +1,6 @@

Drivers

+The following is the complete list of driver configuration parameters, as generated by `mbed compile --config -v`. Please see [the Configuration system documentation](/docs/tools/config_system.md) for details on how you may use or override these settings. ``` Configuration parameters ------------------------ diff --git a/docs/reference/configuration/Platform.md b/docs/reference/configuration/Platform.md index 0e16c80728..45c81bceda 100644 --- a/docs/reference/configuration/Platform.md +++ b/docs/reference/configuration/Platform.md @@ -1,5 +1,7 @@

Platform

+The following is the complete list of platform configuration parameters, as generated by `mbed compile --config -v`. Please see [the Configuration system documentation](/docs/tools/config_system.md) for details on how you may use or override these settings. + ``` Configuration parameters ------------------------ diff --git a/docs/reference/configuration/RTOS.md b/docs/reference/configuration/RTOS.md index 915e0d4d9d..76a0cabc10 100644 --- a/docs/reference/configuration/RTOS.md +++ b/docs/reference/configuration/RTOS.md @@ -8,6 +8,9 @@ All threads in Mbed OS share a global heap. By default, mbed OS dynamically allo By default, there are four threads running after boot: the ISR/scheduler thread, the idle thread, the timer thread and the main application thread. Combined, the idle thread, timer thread and ISR/scheduler thread consume 2 kilobytes of RAM. The user cannot modify these. You can expand or reduce the size of the main application thread stack by using the Mbed configuration system. + +The following is the complete list of RTOS configuration parameters, as generated by `mbed compile --config -v`. Please see [the Configuration system documentation](/docs/tools/config_system.md) for details on how you may use or override these settings. + ``` Configuration parameters ------------------------ From ef9087dc7c18d274314f48655c26ba18aea1b784 Mon Sep 17 00:00:00 2001 From: Jimmy Brisson Date: Thu, 22 Mar 2018 10:55:10 -0500 Subject: [PATCH 12/21] Move configuration system documentation --- docs.json | 4 - docs/reference/configuration/Connectivity.md | 2 +- docs/reference/configuration/Drivers.md | 2 +- docs/reference/configuration/Platform.md | 2 +- docs/reference/configuration/RTOS.md | 2 +- docs/reference/configuration/configuration.md | 274 ++++++++++++++++-- docs/tools/config_system.md | 274 ------------------ 7 files changed, 254 insertions(+), 306 deletions(-) delete mode 100644 docs/tools/config_system.md diff --git a/docs.json b/docs.json index f922175252..9501ca4f99 100644 --- a/docs.json +++ b/docs.json @@ -665,10 +665,6 @@ "title": "Configuring Tools", "sources": [{ "type": "markdown", - "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/tools/config_system.md" - }, - { - "type": "markdown", "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/tools/bootloader.md" }, { diff --git a/docs/reference/configuration/Connectivity.md b/docs/reference/configuration/Connectivity.md index d5277264fa..5cbab0bae7 100644 --- a/docs/reference/configuration/Connectivity.md +++ b/docs/reference/configuration/Connectivity.md @@ -1,7 +1,7 @@

Connectivity

-You can configure various parameters using either C++ APIs or the Arm Mbed configuration system. The following is the complete list of Connectivity configuration parameters, as generated by `mbed compile --config -v`. Please see [the Configuration system documentation](/docs/tools/config_system.md) for details on how you may use or override these settings. +You can configure various parameters using either C++ APIs or the Arm Mbed configuration system. The following is the complete list of Connectivity configuration parameters, as generated by `mbed compile --config -v`. Please see [the Configuration system documentation](/docs/reference/configuration/configuration.md) for details on how you may use or override these settings. ``` Configuration parameters diff --git a/docs/reference/configuration/Drivers.md b/docs/reference/configuration/Drivers.md index 683659385b..b14d0738ff 100644 --- a/docs/reference/configuration/Drivers.md +++ b/docs/reference/configuration/Drivers.md @@ -1,6 +1,6 @@

Drivers

-The following is the complete list of driver configuration parameters, as generated by `mbed compile --config -v`. Please see [the Configuration system documentation](/docs/tools/config_system.md) for details on how you may use or override these settings. +The following is the complete list of driver configuration parameters, as generated by `mbed compile --config -v`. Please see [the Configuration system documentation](/docs/reference/configuration/configuration.md) for details on how you may use or override these settings. ``` Configuration parameters ------------------------ diff --git a/docs/reference/configuration/Platform.md b/docs/reference/configuration/Platform.md index 45c81bceda..99efb90121 100644 --- a/docs/reference/configuration/Platform.md +++ b/docs/reference/configuration/Platform.md @@ -1,6 +1,6 @@

Platform

-The following is the complete list of platform configuration parameters, as generated by `mbed compile --config -v`. Please see [the Configuration system documentation](/docs/tools/config_system.md) for details on how you may use or override these settings. +The following is the complete list of platform configuration parameters, as generated by `mbed compile --config -v`. Please see [the Configuration system documentation](/docs/reference/configuration/configuration.md) for details on how you may use or override these settings. ``` Configuration parameters diff --git a/docs/reference/configuration/RTOS.md b/docs/reference/configuration/RTOS.md index 76a0cabc10..07e9894b05 100644 --- a/docs/reference/configuration/RTOS.md +++ b/docs/reference/configuration/RTOS.md @@ -9,7 +9,7 @@ All threads in Mbed OS share a global heap. By default, mbed OS dynamically allo By default, there are four threads running after boot: the ISR/scheduler thread, the idle thread, the timer thread and the main application thread. Combined, the idle thread, timer thread and ISR/scheduler thread consume 2 kilobytes of RAM. The user cannot modify these. You can expand or reduce the size of the main application thread stack by using the Mbed configuration system. -The following is the complete list of RTOS configuration parameters, as generated by `mbed compile --config -v`. Please see [the Configuration system documentation](/docs/tools/config_system.md) for details on how you may use or override these settings. +The following is the complete list of RTOS configuration parameters, as generated by `mbed compile --config -v`. Please see [the Configuration system documentation](/docs/reference/configuration/configuration.md) for details on how you may use or override these settings. ``` Configuration parameters diff --git a/docs/reference/configuration/configuration.md b/docs/reference/configuration/configuration.md index 621a569dbb..7d0f362c64 100644 --- a/docs/reference/configuration/configuration.md +++ b/docs/reference/configuration/configuration.md @@ -1,48 +1,274 @@ -## Configuration overview +## The configuration system -The Arm Mbed configuration system customizes the compile time configuration of Mbed components: targets, libraries and applications. +The Arm Mbed OS configuration system, a part of the Arm Mbed OS Build Tools, customizes compile time configuration parameters. Each library may define a number of configuration parameters in its `mbed_lib.json`. The values of these configuration parameters may be overridden by `mbed_app.json`. Configuration is defined using [JSON](http://www.json.org/). Some examples of configuration parameters: -Mbed OS provides some default memory configurations for thread memory allocation. You may want to modify these configurations to better suit your project. You can read about the default configurations and how you can modify them below. +- The sampling period for a data acquisition application. +- The default stack size for a newly created OS thread. +- The receive buffer size of a serial communication library. +- The flash and RAM memory size of an Mbed target. -#### Configuring the main thread stack -The default stack size of the main application thread is 4 kilobytes. This memory is dynamically allocated from the global heap. You can configure the stack size of the main thread by using the [Mbed config system](/docs/development/reference/configuration.html). To reduce the stack size from 4K to 2K, create an `mbed_app.json` file for your project with the following content: +The Arm Mbed OS configuration system gathers and interprets the configuration defined in the target in its [target configuration](/docs/development/tools/adding-and-configuring-targets.html), all `mbed_lib.json` files and the `mbed_app.json` file. The configuration system creates a single header file, `mbed_config.h`, that contains all of the defined configuration parameters converted into C preprocessor macros. `mbed compile` places `mbed_config.h` in the build directory and `mbed export` places it in the application root. The Arm Mbed OS configuration system is run during `mbed compile` before invoking the compiler and during `mbed export` before creating project files. + +**Note:** Throughout this document, library mean any reusable piece of code within its own directory. + +**Note:** In prior releases, the configuration system provided a method for adding custom targets. The Mbed OS tools now look for custom targets in a file named `custom_targets.json` in the root of an application and treat custom targets the same as [Mbed targets](/docs/development/tools/adding-and-configuring-targets.html). + +### Examining available configuration parameters + +Mbed CLI includes a command for listing and explaining the compile time configuration, `mbed compile --config`. This command prints a summary of configuration parameters, such as: +``` +Configuration parameters +------------------------ +cellular.random_max_start_delay = 0 (macro name: "MBED_CONF_CELLULAR_RANDOM_MAX_START_DELAY") +cellular.use-apn-lookup = 1 (macro name: "MBED_CONF_CELLULAR_USE_APN_LOOKUP") +configuration-store.storage_disable = 0 (macro name: "CFSTORE_STORAGE_DISABLE") +drivers.uart-serial-rxbuf-size = 256 (macro name: "MBED_CONF_DRIVERS_UART_SERIAL_RXBUF_SIZE") +drivers.uart-serial-txbuf-size = 256 (macro name: "MBED_CONF_DRIVERS_UART_SERIAL_TXBUF_SIZE") +events.present = 1 (macro name: "MBED_CONF_EVENTS_PRESENT") +events.shared-dispatch-from-application = 0 (macro name: "MBED_CONF_EVENTS_SHARED_DISPATCH_FROM_APPLICATION") +events.shared-eventsize = 256 (macro name: "MBED_CONF_EVENTS_SHARED_EVENTSIZE") +events.shared-highprio-eventsize = 256 (macro name: "MBED_CONF_EVENTS_SHARED_HIGHPRIO_EVENTSIZE") +events.shared-highprio-stacksize = 1024 (macro name: "MBED_CONF_EVENTS_SHARED_HIGHPRIO_STACKSIZE") +events.shared-stacksize = 1024 (macro name: "MBED_CONF_EVENTS_SHARED_STACKSIZE") + +``` + +You may find that configuration naming does not always describe the parameter's purpose adequately. Include the `-v` switch to include the help text defined with the configuration parameter, where the value of the configuration parameter is defined, and other details. The command `mbed compile --config -v` in the same application as above prints: +``` +Configuration parameters +------------------------ +Name: cellular.random_max_start_delay + Description: Maximum random delay value used in start-up sequence in milliseconds + Defined by: library:cellular + No value set +Name: cellular.use-apn-lookup + Description: Use APN database lookup + Defined by: library:cellular + Macro name: MBED_CONF_CELLULAR_USE_APN_LOOKUP + Value: 1 (set by library:cellular) +Name: configuration-store.storage_disable + Description: Configuration parameter to disable flash storage if present. Default = 0, implying that by default flash storage is used if present. + Defined by: library:configuration-store + No value set + +``` + +### Using configuration data in code + +When compiling or exporting, the configuration system generates C preprocessor macro definitions of the configuration parameters. The configuration system writes these definitions in a file named `mbed_config.h` located in the build directory. When compiling the same example as the prior section for target `K64F`, the `mbed_config.h` file includes this snippet (note that the order of the definitions may be different): + +```C +// Automatically generated configuration file. +// DO NOT EDIT, content will be overwritten. + +#ifndef __MBED_CONFIG_DATA__ +#define __MBED_CONFIG_DATA__ + +// Configuration parameters +#define MBED_CONF_CELLULAR_RANDOM_MAX_START_DELAY 0 // set by library:cellular +#define MBED_CONF_CELLULAR_USE_APN_LOOKUP 1 // set by library:cellular + +``` + +The name of the macro for a configuration parameter is either a prefixed name or explicitly specified by `macro_name`. A prefixed name is constructed from the prefix `MBED_CONF_`, followed by the name of the library or `APP`, followed by the name of the parameter. The prefixed name is then capitalized and converted to a valid C macro name. For example, the `random_max_start_delay` configuration parameter in the library `cellular` is converted to `MBED_CONF_CELLULAR_RANDOM_MAX_START_DELAY`. + +The Mbed OS build tools instruct the compiler to process the file `mbed_config.h` as if it were the first include of any C or C++ source file, so you do not have to include `mbed_config.h` manually. + +Do not edit `mbed_config.h` manually. It may be overwritten the next time you compile or export your application, and all your changes will be lost. + +### Configuration parameters in `mbed_app.json`, `mbed_lib.json` + +An application may have one `mbed_app.json` in the root of the application and many `mbed_lib.json` files throughout the application. When present, `mbed_app.json` may override configuration parameters defined in libraries and the target and define new configuration parameters. + +#### Overriding configuration parameters + +The configuration system allows a user to override any defined configuration parameter with a JSON object named `"target_overrides"`. + +The keys in the `"target_overrides"` section are the names of a target that the overrides apply to, or the special wildcard `*` that applies to all targets. The values within the `"target_overrides"` section are an object mapping configuration parameters, as printed by `mbed compile --conifg`, to new values. An example `"target_overrides"` section is provided below. + +```JSON +"target_overrides": { + "*": { + "cellular.random_max_start_delay": "100" + }, + "K64F": { + "cellular.use-apn-lookup": false + } +} +``` + +Examining the configuration for the target `LPC1768` with `mbed compile --config -m LPC1768` results in the following configuration: + +``` +Configuration parameters +------------------------ +cellular.random_max_start_delay = 100 (macro name: "MBED_CONF_CELLULAR_RANDOM_MAX_START_DELAY") +cellular.use-apn-lookup = 1 (macro name: "MBED_CONF_CELLULAR_USE_APN_LOOKUP") + +``` + +Examining the configuration for the target `K64F` with `mbed compile --config -m K64F` results in the following configuration: + +``` +Configuration parameters +------------------------ +cellular.random_max_start_delay = 100 (macro name: "MBED_CONF_CELLULAR_RANDOM_MAX_START_DELAY") +cellular.use-apn-lookup = 0 (macro name: "MBED_CONF_CELLULAR_USE_APN_LOOKUP") + +``` + +The order in which overrides are considered is: + + 1. Libraries override target configuration with `mbed_lib.json`. + 2. The application overrides target and library configuration with `mbed_app.json` + +#### Defining configuration parameters + +The configuration system understands configuration parameters defined in targets, libraries and applications. The configuration parameters are always defined in a JSON object called "config". + +For example: ```JSON { "config": { - "main-stack-size": { - "value": 2000 - } + "param1": { + "help": "The first configuration parameter", + "macro_name": "CUSTOM_MACRO_NAME", + "value": 0 + }, + "param2": { + "help": "The second configuration parameter", + "required": true + }, + "param3": 10 } } ``` -#### Configuring user spawned thread stacks +You define a configuration parameter by specifying its name as the key and specifying its value either with a description object or by value. The JSON fragment above defines three configuration parameters named `param1`, `param2` and `param3`. + +Above, the configuration parameters `param1` and `param2` are defined using a description object. The following keys are supported on the description object: + - `help`: an optional help message that describes the purpose of the parameter. + - `value`: an optional field that defines the value of the parameter. + - `required`: an optional key that specifies whether the parameter must be given a value before compiling the code (`false` by default). It's not possible to compile a source tree with one or more required parameters that don't have a value. Generally, setting `required` to true is only useful when `value` is not set. + - `macro_name`: an optional name for the macro defined at compile time for this configuration parameter. The configuration system will automatically figure out the corresponding macro name for a configuration parameter, but the user can override this automatically computed name by specifying `macro_name`. + +You define a macro by value by using an integer or string instead of the description object, such as `param3` above. Defining a parameter by value is equivalent to a configuration parameter defined with a description object with the key `value` set to the value in place of the description object, the key `help` unset, the key `macro_name` unset, and the key `required` set to `false`. + +**Note:** The name of a parameter in `config` can't contain a dot (`.`) character. + +The configuration system appends a prefix to the name of each parameter, so a parameter with the same name in a library does not conflict with parameters of the same name in targets or other libraries. The prefix is: + +| Location | Prefix | +| -------- | ------ | +| target | `target.` | +| any library | The name of the library, as found in the `name` section of `mbed_lib.json`, followed by a dot (.) | +| application | `app.` | + +### `mbed_lib.json` format specification -The default stack size of a user spawned thread is 4 kilobytes. You can configure the stack size of user spawned threads by using the [Mbed config system](/docs/development/tools/index.html#the-configuration-system) or passing in the [Thread constructor](/docs/development/reference/thread.html). You can reduce the default stack size for user spawned threads from 4K to 2K in the following two ways: +`mbed_lib.json` is a JSON formatted document that contains a root JSON Object. The keys within this object are refered to as sections. The allowed sections and their meaning is listed below: -1. Create an `mbed_app.json` file for your project with the following content: +| Section | Required | Meaning | +| ------- | -------- | ------- | +| `name` | Yes | name of the library. Must be unique. May not be `app` or `target`.| +| `macros` | No | List of macros to define on the command line. | +| `config` | No | Configuration parameters defined for use in this library. | +| `target_overrides` | No | Overrides for target configuration parameters and configuration parameters of the current library. | - ```JSON - { - "config": { - "thread-stack-size": { - "value": 2000 - } +The following is an example library, "mylib". + +```JSON +{ + "name": "mylib", + "config": { + "buffer_size": 1024, + "timer_period": { + "help": "The timer period (in us)", + "macro_name": "INTERNAL_GPTMR_PERIOD", + "required": true + }, + "queue_size": { + "help": "Size of event queue (entries)", + "value": 10 + } + }, + "macros": ["MYMOD_MACRO1", "MYMOD_MACRO2=\"TEST\""], + "target_overrides": { + "K64F": { + "timer_period": 100, + "queue_size": 40 + }, + "NXP": { + "queue_size": 20, + "buffer_size": 128, + "target.features_add": ["IPV4"] } } - ``` +} +``` + +In this JSON file: + +- `name` is the name of the library. **This is a required field.** +- `config` defines the configuration parameters of the library, as explained in the section about [defining configuration parameters](#defining-configuration-parameters). +- `macros` is a list of extra macros that will be defined when compiling a application that includes this library. A macro can be defined without a value (such as `MYMOD_MACRO1` above) or with a value (such as `MYMOD_MACRO2` above). +- `target_overrides` is a dictionary with target-specific values for the configuration parameters. -2. Construct the thread like this in your application: +All configuration parameters defined in `mylib` have a `mylib.` prefix. In a `mbed_app.json`, `buffer_size` is accessible using the name `mylib.buffer_size`. +`target_overrides` is used to override the values of the parameters depending on the current compilation target. The keys in `target_overrides` are matched against target labels. (You can find a description of Mbed targets in our documentation about [adding and configuring targets](/docs/development/tools/adding-and-configuring-targets.html).) If a key inside `target_overrides` matches one of the target labels, the parameter values are changed according to the value of the key. - `Thread thread(osPriorityNormal, 2000);` +It is an error for `mbed_lib.json` to override configuration parameters that were not defined. -By default, mbed OS dynamically allocates the memory for the thread's stack from the global heap, though you can change it in the [Thread constructor](/docs/development/reference/thread.html). Here is an example application that uses memory allocated from the main thread's stack for the newly spawned thread stack: +#### Overriding target attributes +Target configurations contain a set of attributes that you may manipulate with configuration. You may override these attributes as if they were a normal configuration parameter. Attributes may be cumulative, in which case they are a list of items. You may add to a cumulative attribute by overriding a configuration parameter with the name of the cumulative attribute suffixed with `_add` and remove from a cumulative attribute with the suffix `_remove`. When overriding, adding or subtracting from a cumulative attribute, the value must be a list of items to replace the definition with, add or remove. For example, you add the value `IPV4` to a target's features list with the syntax: + +```JSON +"target.features_add": ["IPV4"] ``` -int main() { - uint32_t stack_on_main_stack[128 / sizeof(uint32_t)]; // 128 bytes - Thread thread(osPriorityNormal, sizeof(stack_on_main_stack), stack_on_main_stack); + +It is an error to both add and subtract the same value from a cumulative attribute. Find a list of the attributes that may be overwritten in our documentation about [adding and configuring targets](/docs/development/tools/adding-and-configuring-targets.html) + + +### `mbed_app.json` Specification + +`mbed_app.json` may be present at the root of your application or specified as the argument to the `--app-config` parameter. Unlike library configuration, only one `mbed_app.json` is interpreted during `mbed compile` or `mbed export`. Like `mbed_lib.json`, `mbed_app.json` is a JSON formatted document that contains a root JSON Object. The keys within this object are refered to as sections. The allowed sections and their meaning is listed below: + +| Section | Required | Meaning | +| ------- | -------- | ------- | +| `artifact_name` | No | The name for the executable to generate. Defaults to the name of the containing directory. | +| `macros` | No | List of macros to define on the command line. | +| `config` | No | Configuration parameters defined for use in this library. | +| `target_overrides` | No | Overrides for target, library and application configuration parameters. | + +The application can freely override the configuration of any of the libraries it depends on, as well as the configuration data in targets, so it has complete control over the configuration of the whole build. For example, an `mbed_app.json` from an application that depends on `mylib` above may look like this: + +```JSON +{ + "config": { + "welcome_string": { + "help": "The string printed on the display on start-up", + "value": "\"Hello!\"" + } + }, + "target_overrides": { + "*": { + "mylib.timer_period": 100 + }, + "NCS36510": { + "target.mac_addr_high": "0x11223344" + } + } } ``` + +The application may override any configuration parameter by specifying the configuration parameters including their prefix (like `mylib.timer_period`). If an overridden parameter doesn't have a prefix, it overrides a parameter in its own `config` section. + +The `mbed_app.json` above defines its own configuration parameter (`welcome_string`) and overrides the configuration in both the target (`target.mac_addr_high`) and its `mylib` dependency (`mylib.timer_period`): + +- When compiling for `NCS36510`, `app.welcome_string` is `"Hello!"`, `target.mac_addr_high` is `"0x11223344"` (from the `NCS36510` override) and `mylib.timer_period` is 100 (from the `*` override). +- When compiling for `LPC1768`, `app.welcome_string` is `"Hello!"` and `mylib.timer_period` is 100 (also from the `*` override). + +It is an error for the application configuration to override configuration parameters that were not defined. diff --git a/docs/tools/config_system.md b/docs/tools/config_system.md deleted file mode 100644 index 7d0f362c64..0000000000 --- a/docs/tools/config_system.md +++ /dev/null @@ -1,274 +0,0 @@ -## The configuration system - -The Arm Mbed OS configuration system, a part of the Arm Mbed OS Build Tools, customizes compile time configuration parameters. Each library may define a number of configuration parameters in its `mbed_lib.json`. The values of these configuration parameters may be overridden by `mbed_app.json`. Configuration is defined using [JSON](http://www.json.org/). Some examples of configuration parameters: - -- The sampling period for a data acquisition application. -- The default stack size for a newly created OS thread. -- The receive buffer size of a serial communication library. -- The flash and RAM memory size of an Mbed target. - - -The Arm Mbed OS configuration system gathers and interprets the configuration defined in the target in its [target configuration](/docs/development/tools/adding-and-configuring-targets.html), all `mbed_lib.json` files and the `mbed_app.json` file. The configuration system creates a single header file, `mbed_config.h`, that contains all of the defined configuration parameters converted into C preprocessor macros. `mbed compile` places `mbed_config.h` in the build directory and `mbed export` places it in the application root. The Arm Mbed OS configuration system is run during `mbed compile` before invoking the compiler and during `mbed export` before creating project files. - -**Note:** Throughout this document, library mean any reusable piece of code within its own directory. - -**Note:** In prior releases, the configuration system provided a method for adding custom targets. The Mbed OS tools now look for custom targets in a file named `custom_targets.json` in the root of an application and treat custom targets the same as [Mbed targets](/docs/development/tools/adding-and-configuring-targets.html). - -### Examining available configuration parameters - -Mbed CLI includes a command for listing and explaining the compile time configuration, `mbed compile --config`. This command prints a summary of configuration parameters, such as: -``` -Configuration parameters ------------------------- -cellular.random_max_start_delay = 0 (macro name: "MBED_CONF_CELLULAR_RANDOM_MAX_START_DELAY") -cellular.use-apn-lookup = 1 (macro name: "MBED_CONF_CELLULAR_USE_APN_LOOKUP") -configuration-store.storage_disable = 0 (macro name: "CFSTORE_STORAGE_DISABLE") -drivers.uart-serial-rxbuf-size = 256 (macro name: "MBED_CONF_DRIVERS_UART_SERIAL_RXBUF_SIZE") -drivers.uart-serial-txbuf-size = 256 (macro name: "MBED_CONF_DRIVERS_UART_SERIAL_TXBUF_SIZE") -events.present = 1 (macro name: "MBED_CONF_EVENTS_PRESENT") -events.shared-dispatch-from-application = 0 (macro name: "MBED_CONF_EVENTS_SHARED_DISPATCH_FROM_APPLICATION") -events.shared-eventsize = 256 (macro name: "MBED_CONF_EVENTS_SHARED_EVENTSIZE") -events.shared-highprio-eventsize = 256 (macro name: "MBED_CONF_EVENTS_SHARED_HIGHPRIO_EVENTSIZE") -events.shared-highprio-stacksize = 1024 (macro name: "MBED_CONF_EVENTS_SHARED_HIGHPRIO_STACKSIZE") -events.shared-stacksize = 1024 (macro name: "MBED_CONF_EVENTS_SHARED_STACKSIZE") - -``` - -You may find that configuration naming does not always describe the parameter's purpose adequately. Include the `-v` switch to include the help text defined with the configuration parameter, where the value of the configuration parameter is defined, and other details. The command `mbed compile --config -v` in the same application as above prints: -``` -Configuration parameters ------------------------- -Name: cellular.random_max_start_delay - Description: Maximum random delay value used in start-up sequence in milliseconds - Defined by: library:cellular - No value set -Name: cellular.use-apn-lookup - Description: Use APN database lookup - Defined by: library:cellular - Macro name: MBED_CONF_CELLULAR_USE_APN_LOOKUP - Value: 1 (set by library:cellular) -Name: configuration-store.storage_disable - Description: Configuration parameter to disable flash storage if present. Default = 0, implying that by default flash storage is used if present. - Defined by: library:configuration-store - No value set - -``` - -### Using configuration data in code - -When compiling or exporting, the configuration system generates C preprocessor macro definitions of the configuration parameters. The configuration system writes these definitions in a file named `mbed_config.h` located in the build directory. When compiling the same example as the prior section for target `K64F`, the `mbed_config.h` file includes this snippet (note that the order of the definitions may be different): - -```C -// Automatically generated configuration file. -// DO NOT EDIT, content will be overwritten. - -#ifndef __MBED_CONFIG_DATA__ -#define __MBED_CONFIG_DATA__ - -// Configuration parameters -#define MBED_CONF_CELLULAR_RANDOM_MAX_START_DELAY 0 // set by library:cellular -#define MBED_CONF_CELLULAR_USE_APN_LOOKUP 1 // set by library:cellular - -``` - -The name of the macro for a configuration parameter is either a prefixed name or explicitly specified by `macro_name`. A prefixed name is constructed from the prefix `MBED_CONF_`, followed by the name of the library or `APP`, followed by the name of the parameter. The prefixed name is then capitalized and converted to a valid C macro name. For example, the `random_max_start_delay` configuration parameter in the library `cellular` is converted to `MBED_CONF_CELLULAR_RANDOM_MAX_START_DELAY`. - -The Mbed OS build tools instruct the compiler to process the file `mbed_config.h` as if it were the first include of any C or C++ source file, so you do not have to include `mbed_config.h` manually. - -Do not edit `mbed_config.h` manually. It may be overwritten the next time you compile or export your application, and all your changes will be lost. - -### Configuration parameters in `mbed_app.json`, `mbed_lib.json` - -An application may have one `mbed_app.json` in the root of the application and many `mbed_lib.json` files throughout the application. When present, `mbed_app.json` may override configuration parameters defined in libraries and the target and define new configuration parameters. - -#### Overriding configuration parameters - -The configuration system allows a user to override any defined configuration parameter with a JSON object named `"target_overrides"`. - -The keys in the `"target_overrides"` section are the names of a target that the overrides apply to, or the special wildcard `*` that applies to all targets. The values within the `"target_overrides"` section are an object mapping configuration parameters, as printed by `mbed compile --conifg`, to new values. An example `"target_overrides"` section is provided below. - -```JSON -"target_overrides": { - "*": { - "cellular.random_max_start_delay": "100" - }, - "K64F": { - "cellular.use-apn-lookup": false - } -} -``` - -Examining the configuration for the target `LPC1768` with `mbed compile --config -m LPC1768` results in the following configuration: - -``` -Configuration parameters ------------------------- -cellular.random_max_start_delay = 100 (macro name: "MBED_CONF_CELLULAR_RANDOM_MAX_START_DELAY") -cellular.use-apn-lookup = 1 (macro name: "MBED_CONF_CELLULAR_USE_APN_LOOKUP") - -``` - -Examining the configuration for the target `K64F` with `mbed compile --config -m K64F` results in the following configuration: - -``` -Configuration parameters ------------------------- -cellular.random_max_start_delay = 100 (macro name: "MBED_CONF_CELLULAR_RANDOM_MAX_START_DELAY") -cellular.use-apn-lookup = 0 (macro name: "MBED_CONF_CELLULAR_USE_APN_LOOKUP") - -``` - -The order in which overrides are considered is: - - 1. Libraries override target configuration with `mbed_lib.json`. - 2. The application overrides target and library configuration with `mbed_app.json` - -#### Defining configuration parameters - -The configuration system understands configuration parameters defined in targets, libraries and applications. The configuration parameters are always defined in a JSON object called "config". - -For example: - -```JSON -{ - "config": { - "param1": { - "help": "The first configuration parameter", - "macro_name": "CUSTOM_MACRO_NAME", - "value": 0 - }, - "param2": { - "help": "The second configuration parameter", - "required": true - }, - "param3": 10 - } -} -``` - -You define a configuration parameter by specifying its name as the key and specifying its value either with a description object or by value. The JSON fragment above defines three configuration parameters named `param1`, `param2` and `param3`. - -Above, the configuration parameters `param1` and `param2` are defined using a description object. The following keys are supported on the description object: - - `help`: an optional help message that describes the purpose of the parameter. - - `value`: an optional field that defines the value of the parameter. - - `required`: an optional key that specifies whether the parameter must be given a value before compiling the code (`false` by default). It's not possible to compile a source tree with one or more required parameters that don't have a value. Generally, setting `required` to true is only useful when `value` is not set. - - `macro_name`: an optional name for the macro defined at compile time for this configuration parameter. The configuration system will automatically figure out the corresponding macro name for a configuration parameter, but the user can override this automatically computed name by specifying `macro_name`. - -You define a macro by value by using an integer or string instead of the description object, such as `param3` above. Defining a parameter by value is equivalent to a configuration parameter defined with a description object with the key `value` set to the value in place of the description object, the key `help` unset, the key `macro_name` unset, and the key `required` set to `false`. - -**Note:** The name of a parameter in `config` can't contain a dot (`.`) character. - -The configuration system appends a prefix to the name of each parameter, so a parameter with the same name in a library does not conflict with parameters of the same name in targets or other libraries. The prefix is: - -| Location | Prefix | -| -------- | ------ | -| target | `target.` | -| any library | The name of the library, as found in the `name` section of `mbed_lib.json`, followed by a dot (.) | -| application | `app.` | - -### `mbed_lib.json` format specification - -`mbed_lib.json` is a JSON formatted document that contains a root JSON Object. The keys within this object are refered to as sections. The allowed sections and their meaning is listed below: - -| Section | Required | Meaning | -| ------- | -------- | ------- | -| `name` | Yes | name of the library. Must be unique. May not be `app` or `target`.| -| `macros` | No | List of macros to define on the command line. | -| `config` | No | Configuration parameters defined for use in this library. | -| `target_overrides` | No | Overrides for target configuration parameters and configuration parameters of the current library. | - -The following is an example library, "mylib". - -```JSON -{ - "name": "mylib", - "config": { - "buffer_size": 1024, - "timer_period": { - "help": "The timer period (in us)", - "macro_name": "INTERNAL_GPTMR_PERIOD", - "required": true - }, - "queue_size": { - "help": "Size of event queue (entries)", - "value": 10 - } - }, - "macros": ["MYMOD_MACRO1", "MYMOD_MACRO2=\"TEST\""], - "target_overrides": { - "K64F": { - "timer_period": 100, - "queue_size": 40 - }, - "NXP": { - "queue_size": 20, - "buffer_size": 128, - "target.features_add": ["IPV4"] - } - } -} -``` - -In this JSON file: - -- `name` is the name of the library. **This is a required field.** -- `config` defines the configuration parameters of the library, as explained in the section about [defining configuration parameters](#defining-configuration-parameters). -- `macros` is a list of extra macros that will be defined when compiling a application that includes this library. A macro can be defined without a value (such as `MYMOD_MACRO1` above) or with a value (such as `MYMOD_MACRO2` above). -- `target_overrides` is a dictionary with target-specific values for the configuration parameters. - -All configuration parameters defined in `mylib` have a `mylib.` prefix. In a `mbed_app.json`, `buffer_size` is accessible using the name `mylib.buffer_size`. -`target_overrides` is used to override the values of the parameters depending on the current compilation target. The keys in `target_overrides` are matched against target labels. (You can find a description of Mbed targets in our documentation about [adding and configuring targets](/docs/development/tools/adding-and-configuring-targets.html).) If a key inside `target_overrides` matches one of the target labels, the parameter values are changed according to the value of the key. - -It is an error for `mbed_lib.json` to override configuration parameters that were not defined. - -#### Overriding target attributes - -Target configurations contain a set of attributes that you may manipulate with configuration. You may override these attributes as if they were a normal configuration parameter. Attributes may be cumulative, in which case they are a list of items. You may add to a cumulative attribute by overriding a configuration parameter with the name of the cumulative attribute suffixed with `_add` and remove from a cumulative attribute with the suffix `_remove`. When overriding, adding or subtracting from a cumulative attribute, the value must be a list of items to replace the definition with, add or remove. For example, you add the value `IPV4` to a target's features list with the syntax: - -```JSON -"target.features_add": ["IPV4"] -``` - -It is an error to both add and subtract the same value from a cumulative attribute. Find a list of the attributes that may be overwritten in our documentation about [adding and configuring targets](/docs/development/tools/adding-and-configuring-targets.html) - - -### `mbed_app.json` Specification - -`mbed_app.json` may be present at the root of your application or specified as the argument to the `--app-config` parameter. Unlike library configuration, only one `mbed_app.json` is interpreted during `mbed compile` or `mbed export`. Like `mbed_lib.json`, `mbed_app.json` is a JSON formatted document that contains a root JSON Object. The keys within this object are refered to as sections. The allowed sections and their meaning is listed below: - -| Section | Required | Meaning | -| ------- | -------- | ------- | -| `artifact_name` | No | The name for the executable to generate. Defaults to the name of the containing directory. | -| `macros` | No | List of macros to define on the command line. | -| `config` | No | Configuration parameters defined for use in this library. | -| `target_overrides` | No | Overrides for target, library and application configuration parameters. | - -The application can freely override the configuration of any of the libraries it depends on, as well as the configuration data in targets, so it has complete control over the configuration of the whole build. For example, an `mbed_app.json` from an application that depends on `mylib` above may look like this: - -```JSON -{ - "config": { - "welcome_string": { - "help": "The string printed on the display on start-up", - "value": "\"Hello!\"" - } - }, - "target_overrides": { - "*": { - "mylib.timer_period": 100 - }, - "NCS36510": { - "target.mac_addr_high": "0x11223344" - } - } -} -``` - -The application may override any configuration parameter by specifying the configuration parameters including their prefix (like `mylib.timer_period`). If an overridden parameter doesn't have a prefix, it overrides a parameter in its own `config` section. - -The `mbed_app.json` above defines its own configuration parameter (`welcome_string`) and overrides the configuration in both the target (`target.mac_addr_high`) and its `mylib` dependency (`mylib.timer_period`): - -- When compiling for `NCS36510`, `app.welcome_string` is `"Hello!"`, `target.mac_addr_high` is `"0x11223344"` (from the `NCS36510` override) and `mylib.timer_period` is 100 (from the `*` override). -- When compiling for `LPC1768`, `app.welcome_string` is `"Hello!"` and `mylib.timer_period` is 100 (also from the `*` override). - -It is an error for the application configuration to override configuration parameters that were not defined. From bc4ef27eb182de877cfcc64da5e6982d16453a37 Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Thu, 22 Mar 2018 14:17:33 -0500 Subject: [PATCH 13/21] Fix link in Connectivity.md Fix link to point to html instead of md --- docs/reference/configuration/Connectivity.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/configuration/Connectivity.md b/docs/reference/configuration/Connectivity.md index 5cbab0bae7..44ecbb16ce 100644 --- a/docs/reference/configuration/Connectivity.md +++ b/docs/reference/configuration/Connectivity.md @@ -1,7 +1,7 @@

Connectivity

-You can configure various parameters using either C++ APIs or the Arm Mbed configuration system. The following is the complete list of Connectivity configuration parameters, as generated by `mbed compile --config -v`. Please see [the Configuration system documentation](/docs/reference/configuration/configuration.md) for details on how you may use or override these settings. +You can configure various parameters using either C++ APIs or the Arm Mbed configuration system. The following is the complete list of Connectivity configuration parameters, as generated by `mbed compile --config -v`. Please see [the Configuration system documentation](/docs/development/reference/configuration.html) for details on how you may use or override these settings. ``` Configuration parameters From e2446a808eaa812eba7772f41180cf892022e388 Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Thu, 22 Mar 2018 14:18:23 -0500 Subject: [PATCH 14/21] Fix link in Drivers.md Update link. --- docs/reference/configuration/Drivers.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/reference/configuration/Drivers.md b/docs/reference/configuration/Drivers.md index b14d0738ff..e3e3bd7ad0 100644 --- a/docs/reference/configuration/Drivers.md +++ b/docs/reference/configuration/Drivers.md @@ -1,6 +1,7 @@

Drivers

-The following is the complete list of driver configuration parameters, as generated by `mbed compile --config -v`. Please see [the Configuration system documentation](/docs/reference/configuration/configuration.md) for details on how you may use or override these settings. +The following is the complete list of driver configuration parameters, as generated by `mbed compile --config -v`. Please see [the Configuration system documentation](/docs/development/reference/configuration.html) for details on how you may use or override these settings. + ``` Configuration parameters ------------------------ From ab8b7dc0e78f9e3dbfa2bf08c30563dbe040c7cc Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Thu, 22 Mar 2018 14:18:59 -0500 Subject: [PATCH 15/21] Fix link in Platform.md Update link. --- docs/reference/configuration/Platform.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/configuration/Platform.md b/docs/reference/configuration/Platform.md index 99efb90121..42a5b4fe42 100644 --- a/docs/reference/configuration/Platform.md +++ b/docs/reference/configuration/Platform.md @@ -1,6 +1,6 @@

Platform

-The following is the complete list of platform configuration parameters, as generated by `mbed compile --config -v`. Please see [the Configuration system documentation](/docs/reference/configuration/configuration.md) for details on how you may use or override these settings. +The following is the complete list of platform configuration parameters, as generated by `mbed compile --config -v`. Please see [the Configuration system documentation](/docs/development/reference/configuration.html) for details on how you may use or override these settings. ``` Configuration parameters From 17a3340eddeb61d37d5b7b8132abeb493334e39b Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Thu, 22 Mar 2018 14:19:35 -0500 Subject: [PATCH 16/21] Fix link in RTOS.md Update link. --- docs/reference/configuration/RTOS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/configuration/RTOS.md b/docs/reference/configuration/RTOS.md index 07e9894b05..c114bd3467 100644 --- a/docs/reference/configuration/RTOS.md +++ b/docs/reference/configuration/RTOS.md @@ -9,7 +9,7 @@ All threads in Mbed OS share a global heap. By default, mbed OS dynamically allo By default, there are four threads running after boot: the ISR/scheduler thread, the idle thread, the timer thread and the main application thread. Combined, the idle thread, timer thread and ISR/scheduler thread consume 2 kilobytes of RAM. The user cannot modify these. You can expand or reduce the size of the main application thread stack by using the Mbed configuration system. -The following is the complete list of RTOS configuration parameters, as generated by `mbed compile --config -v`. Please see [the Configuration system documentation](/docs/reference/configuration/configuration.md) for details on how you may use or override these settings. +The following is the complete list of RTOS configuration parameters, as generated by `mbed compile --config -v`. Please see [the Configuration system documentation](/docs/development/reference/configuration.html) for details on how you may use or override these settings. ``` Configuration parameters From 227457a78aac49bd81b3108bac463bf3d45e0648 Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Thu, 22 Mar 2018 14:38:33 -0500 Subject: [PATCH 17/21] Copy edit configuration.md Complete minor copy edit, mostly for active voice. --- docs/reference/configuration/configuration.md | 56 ++++++++++--------- 1 file changed, 29 insertions(+), 27 deletions(-) diff --git a/docs/reference/configuration/configuration.md b/docs/reference/configuration/configuration.md index 7d0f362c64..0dd5cd96db 100644 --- a/docs/reference/configuration/configuration.md +++ b/docs/reference/configuration/configuration.md @@ -1,22 +1,22 @@ ## The configuration system -The Arm Mbed OS configuration system, a part of the Arm Mbed OS Build Tools, customizes compile time configuration parameters. Each library may define a number of configuration parameters in its `mbed_lib.json`. The values of these configuration parameters may be overridden by `mbed_app.json`. Configuration is defined using [JSON](http://www.json.org/). Some examples of configuration parameters: +The Arm Mbed OS configuration system, a part of the Arm Mbed OS build tools, customizes compile time configuration parameters. Each library may define a number of configuration parameters in its `mbed_lib.json`. `mbed_app.json` may override the values of these configuration parameters. Configuration is defined using [JSON](http://www.json.org/). Some examples of configuration parameters: - The sampling period for a data acquisition application. - The default stack size for a newly created OS thread. - The receive buffer size of a serial communication library. - The flash and RAM memory size of an Mbed target. +The Arm Mbed OS configuration system gathers and interprets the configuration defined in the target in its [target configuration](/docs/development/tools/adding-and-configuring-targets.html), all `mbed_lib.json` files and the `mbed_app.json` file. The configuration system creates a single header file, `mbed_config.h`, that contains all of the defined configuration parameters converted into C preprocessor macros. `mbed compile` places `mbed_config.h` in the build directory, and `mbed export` places it in the application root. The Arm Mbed OS configuration system is run during `mbed compile` before invoking the compiler and during `mbed export` before creating project files. -The Arm Mbed OS configuration system gathers and interprets the configuration defined in the target in its [target configuration](/docs/development/tools/adding-and-configuring-targets.html), all `mbed_lib.json` files and the `mbed_app.json` file. The configuration system creates a single header file, `mbed_config.h`, that contains all of the defined configuration parameters converted into C preprocessor macros. `mbed compile` places `mbed_config.h` in the build directory and `mbed export` places it in the application root. The Arm Mbed OS configuration system is run during `mbed compile` before invoking the compiler and during `mbed export` before creating project files. - -**Note:** Throughout this document, library mean any reusable piece of code within its own directory. +**Note:** Throughout this document, "library" means any reusable piece of code within its own directory. **Note:** In prior releases, the configuration system provided a method for adding custom targets. The Mbed OS tools now look for custom targets in a file named `custom_targets.json` in the root of an application and treat custom targets the same as [Mbed targets](/docs/development/tools/adding-and-configuring-targets.html). ### Examining available configuration parameters Mbed CLI includes a command for listing and explaining the compile time configuration, `mbed compile --config`. This command prints a summary of configuration parameters, such as: + ``` Configuration parameters ------------------------ @@ -34,7 +34,8 @@ events.shared-stacksize = 1024 (macro name: "MBED_CONF_EVENTS_SHARED_STACKSIZE") ``` -You may find that configuration naming does not always describe the parameter's purpose adequately. Include the `-v` switch to include the help text defined with the configuration parameter, where the value of the configuration parameter is defined, and other details. The command `mbed compile --config -v` in the same application as above prints: +You may find that configuration naming does not always describe the parameter's purpose adequately. Use the `-v` switch to include the help text defined with the configuration parameter, where the value of the configuration parameter is defined, and other details. The command `mbed compile --config -v` in the same application as above prints: + ``` Configuration parameters ------------------------ @@ -75,17 +76,17 @@ The name of the macro for a configuration parameter is either a prefixed name or The Mbed OS build tools instruct the compiler to process the file `mbed_config.h` as if it were the first include of any C or C++ source file, so you do not have to include `mbed_config.h` manually. -Do not edit `mbed_config.h` manually. It may be overwritten the next time you compile or export your application, and all your changes will be lost. +Do not edit `mbed_config.h` manually. It may be overwritten the next time you compile or export your application, and you will lose all your changes. ### Configuration parameters in `mbed_app.json`, `mbed_lib.json` -An application may have one `mbed_app.json` in the root of the application and many `mbed_lib.json` files throughout the application. When present, `mbed_app.json` may override configuration parameters defined in libraries and the target and define new configuration parameters. +An application may have one `mbed_app.json` in the root of the application and many `mbed_lib.json` files throughout the application. When present, `mbed_app.json` may override configuration parameters defined in libraries and the target and define new configuration parameters. #### Overriding configuration parameters The configuration system allows a user to override any defined configuration parameter with a JSON object named `"target_overrides"`. -The keys in the `"target_overrides"` section are the names of a target that the overrides apply to, or the special wildcard `*` that applies to all targets. The values within the `"target_overrides"` section are an object mapping configuration parameters, as printed by `mbed compile --conifg`, to new values. An example `"target_overrides"` section is provided below. +The keys in the `"target_overrides"` section are the names of a target that the overrides apply to, or the special wildcard `*` that applies to all targets. The values within the `"target_overrides"` section are an object mapping configuration parameters, as printed by `mbed compile --conifg`, to new values. See the example `"target_overrides"` section below. ```JSON "target_overrides": { @@ -125,7 +126,7 @@ The order in which overrides are considered is: #### Defining configuration parameters -The configuration system understands configuration parameters defined in targets, libraries and applications. The configuration parameters are always defined in a JSON object called "config". +The configuration system understands configuration parameters that targets, libraries and applications define. A JSON object called "config" always defines the configuration parameters. For example: @@ -149,10 +150,11 @@ For example: You define a configuration parameter by specifying its name as the key and specifying its value either with a description object or by value. The JSON fragment above defines three configuration parameters named `param1`, `param2` and `param3`. Above, the configuration parameters `param1` and `param2` are defined using a description object. The following keys are supported on the description object: + - `help`: an optional help message that describes the purpose of the parameter. - `value`: an optional field that defines the value of the parameter. - `required`: an optional key that specifies whether the parameter must be given a value before compiling the code (`false` by default). It's not possible to compile a source tree with one or more required parameters that don't have a value. Generally, setting `required` to true is only useful when `value` is not set. - - `macro_name`: an optional name for the macro defined at compile time for this configuration parameter. The configuration system will automatically figure out the corresponding macro name for a configuration parameter, but the user can override this automatically computed name by specifying `macro_name`. + - `macro_name`: an optional name for the macro defined at compile time for this configuration parameter. The configuration system automatically figures out the corresponding macro name for a configuration parameter, but the user can override this automatically computed name by specifying `macro_name`. You define a macro by value by using an integer or string instead of the description object, such as `param3` above. Defining a parameter by value is equivalent to a configuration parameter defined with a description object with the key `value` set to the value in place of the description object, the key `help` unset, the key `macro_name` unset, and the key `required` set to `false`. @@ -162,22 +164,22 @@ The configuration system appends a prefix to the name of each parameter, so a pa | Location | Prefix | | -------- | ------ | -| target | `target.` | -| any library | The name of the library, as found in the `name` section of `mbed_lib.json`, followed by a dot (.) | -| application | `app.` | +| Target | `target.` | +| Any library | The name of the library, as found in the `name` section of `mbed_lib.json`, followed by a dot (.) | +| Application | `app.` | ### `mbed_lib.json` format specification -`mbed_lib.json` is a JSON formatted document that contains a root JSON Object. The keys within this object are refered to as sections. The allowed sections and their meaning is listed below: +`mbed_lib.json` is a JSON formatted document that contains a root JSON Object. The keys within this object are sections. See the allowed sections and their meanings below: | Section | Required | Meaning | | ------- | -------- | ------- | -| `name` | Yes | name of the library. Must be unique. May not be `app` or `target`.| -| `macros` | No | List of macros to define on the command line. | +| `name` | Yes | Name of the library. Must be unique. May not be `app` or `target`.| +| `macros` | No | List of macros to define on the command-line. | | `config` | No | Configuration parameters defined for use in this library. | | `target_overrides` | No | Overrides for target configuration parameters and configuration parameters of the current library. | -The following is an example library, "mylib". +The following is an example library, `mylib`. ```JSON { @@ -212,34 +214,34 @@ The following is an example library, "mylib". In this JSON file: - `name` is the name of the library. **This is a required field.** -- `config` defines the configuration parameters of the library, as explained in the section about [defining configuration parameters](#defining-configuration-parameters). -- `macros` is a list of extra macros that will be defined when compiling a application that includes this library. A macro can be defined without a value (such as `MYMOD_MACRO1` above) or with a value (such as `MYMOD_MACRO2` above). +- `config` defines the configuration parameters of the library, as the section about [defining configuration parameters](#defining-configuration-parameters) explains. +- `macros` is a list of extra macros that are defined when compiling a application that includes this library. A macro can be defined without a value (such as `MYMOD_MACRO1` above) or with a value (such as `MYMOD_MACRO2` above). - `target_overrides` is a dictionary with target-specific values for the configuration parameters. -All configuration parameters defined in `mylib` have a `mylib.` prefix. In a `mbed_app.json`, `buffer_size` is accessible using the name `mylib.buffer_size`. -`target_overrides` is used to override the values of the parameters depending on the current compilation target. The keys in `target_overrides` are matched against target labels. (You can find a description of Mbed targets in our documentation about [adding and configuring targets](/docs/development/tools/adding-and-configuring-targets.html).) If a key inside `target_overrides` matches one of the target labels, the parameter values are changed according to the value of the key. +All configuration parameters defined in `mylib` have a `mylib.` prefix. In `mbed_app.json`, `buffer_size` is accessible using the name `mylib.buffer_size`. + +Use `target_overrides` to override the values of the parameters, depending on the current compilation target. The keys in `target_overrides` are matched against target labels. (You can find a description of Mbed targets in our documentation about [adding and configuring targets](/docs/development/tools/adding-and-configuring-targets.html).) If a key inside `target_overrides` matches one of the target labels, the parameter values change according to the value of the key. It is an error for `mbed_lib.json` to override configuration parameters that were not defined. #### Overriding target attributes -Target configurations contain a set of attributes that you may manipulate with configuration. You may override these attributes as if they were a normal configuration parameter. Attributes may be cumulative, in which case they are a list of items. You may add to a cumulative attribute by overriding a configuration parameter with the name of the cumulative attribute suffixed with `_add` and remove from a cumulative attribute with the suffix `_remove`. When overriding, adding or subtracting from a cumulative attribute, the value must be a list of items to replace the definition with, add or remove. For example, you add the value `IPV4` to a target's features list with the syntax: +Target configurations contain a set of attributes that you may manipulate with configuration. You may override these attributes as if they were a normal configuration parameter. Attributes may be cumulative, in which case they are a list of items. You may add to a cumulative attribute by overriding a configuration parameter with the name of the cumulative attribute suffixed with `_add` and remove from a cumulative attribute with the suffix `_remove`. When you override, add to or subtract from a cumulative attribute, the value must be a list of items to replace the definition with, add or remove. For example, add the value `IPV4` to a target's features list with the syntax: ```JSON "target.features_add": ["IPV4"] ``` -It is an error to both add and subtract the same value from a cumulative attribute. Find a list of the attributes that may be overwritten in our documentation about [adding and configuring targets](/docs/development/tools/adding-and-configuring-targets.html) - +It is an error to both add and subtract the same value from a cumulative attribute. For a list of the attributes that you may overwrite, please see our documentation about [adding and configuring targets](/docs/development/tools/adding-and-configuring-targets.html) ### `mbed_app.json` Specification -`mbed_app.json` may be present at the root of your application or specified as the argument to the `--app-config` parameter. Unlike library configuration, only one `mbed_app.json` is interpreted during `mbed compile` or `mbed export`. Like `mbed_lib.json`, `mbed_app.json` is a JSON formatted document that contains a root JSON Object. The keys within this object are refered to as sections. The allowed sections and their meaning is listed below: +`mbed_app.json` may be present at the root of your application or specified as the argument to the `--app-config` parameter. Unlike library configuration, only one `mbed_app.json` is interpreted during `mbed compile` or `mbed export`. Like `mbed_lib.json`, `mbed_app.json` is a JSON formatted document that contains a root JSON Object. The keys within this object are sections. The allowed sections and their meanings are below: | Section | Required | Meaning | | ------- | -------- | ------- | | `artifact_name` | No | The name for the executable to generate. Defaults to the name of the containing directory. | -| `macros` | No | List of macros to define on the command line. | +| `macros` | No | List of macros to define on the command-line. | | `config` | No | Configuration parameters defined for use in this library. | | `target_overrides` | No | Overrides for target, library and application configuration parameters. | @@ -264,7 +266,7 @@ The application can freely override the configuration of any of the libraries it } ``` -The application may override any configuration parameter by specifying the configuration parameters including their prefix (like `mylib.timer_period`). If an overridden parameter doesn't have a prefix, it overrides a parameter in its own `config` section. +The application may override any configuration parameter by specifying the configuration parameters including their prefix (such as `mylib.timer_period`). If an overridden parameter doesn't have a prefix, it overrides a parameter in its own `config` section. The `mbed_app.json` above defines its own configuration parameter (`welcome_string`) and overrides the configuration in both the target (`target.mac_addr_high`) and its `mylib` dependency (`mylib.timer_period`): From 600974d2e105e82ba2be1f280525f37eaaea5a07 Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Mon, 26 Mar 2018 14:34:46 -0500 Subject: [PATCH 18/21] Make changes from comments. Make changes requested by engineering in response to my initial queries. --- docs/reference/configuration/configuration.md | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/reference/configuration/configuration.md b/docs/reference/configuration/configuration.md index 0dd5cd96db..57c8ee9fe3 100644 --- a/docs/reference/configuration/configuration.md +++ b/docs/reference/configuration/configuration.md @@ -7,7 +7,7 @@ The Arm Mbed OS configuration system, a part of the Arm Mbed OS build tools, cus - The receive buffer size of a serial communication library. - The flash and RAM memory size of an Mbed target. -The Arm Mbed OS configuration system gathers and interprets the configuration defined in the target in its [target configuration](/docs/development/tools/adding-and-configuring-targets.html), all `mbed_lib.json` files and the `mbed_app.json` file. The configuration system creates a single header file, `mbed_config.h`, that contains all of the defined configuration parameters converted into C preprocessor macros. `mbed compile` places `mbed_config.h` in the build directory, and `mbed export` places it in the application root. The Arm Mbed OS configuration system is run during `mbed compile` before invoking the compiler and during `mbed export` before creating project files. +The Arm Mbed OS configuration system gathers and interprets the configuration defined in the target in its [target configuration](/docs/development/tools/adding-and-configuring-targets.html), all `mbed_lib.json` files and the `mbed_app.json` file. The configuration system creates a single header file, `mbed_config.h`, that contains all of the defined configuration parameters converted into C preprocessor macros. `mbed compile` places `mbed_config.h` in the build directory, and `mbed export` places it in the application root. `mbed compile` runs the Mbed configuration system before invoking the compiler, and `mbed export` runs the configuration system before creating project files. **Note:** Throughout this document, "library" means any reusable piece of code within its own directory. @@ -72,7 +72,7 @@ When compiling or exporting, the configuration system generates C preprocessor m ``` -The name of the macro for a configuration parameter is either a prefixed name or explicitly specified by `macro_name`. A prefixed name is constructed from the prefix `MBED_CONF_`, followed by the name of the library or `APP`, followed by the name of the parameter. The prefixed name is then capitalized and converted to a valid C macro name. For example, the `random_max_start_delay` configuration parameter in the library `cellular` is converted to `MBED_CONF_CELLULAR_RANDOM_MAX_START_DELAY`. +The name of the macro for a configuration parameter is either a prefixed name or explicitly specified by `macro_name`. The configuration system constructs a prefixed name from the prefix `MBED_CONF_`, followed by the name of the library or `APP`, followed by the name of the parameter. The configuration system then capitalizes the prefixed name and converts it to a valid C macro name. For example, the configuration system converts the `random_max_start_delay` configuration parameter in the library `cellular` to `MBED_CONF_CELLULAR_RANDOM_MAX_START_DELAY`. The Mbed OS build tools instruct the compiler to process the file `mbed_config.h` as if it were the first include of any C or C++ source file, so you do not have to include `mbed_config.h` manually. @@ -86,7 +86,7 @@ An application may have one `mbed_app.json` in the root of the application and m The configuration system allows a user to override any defined configuration parameter with a JSON object named `"target_overrides"`. -The keys in the `"target_overrides"` section are the names of a target that the overrides apply to, or the special wildcard `*` that applies to all targets. The values within the `"target_overrides"` section are an object mapping configuration parameters, as printed by `mbed compile --conifg`, to new values. See the example `"target_overrides"` section below. +The keys in the `"target_overrides"` section are the names of a target that the overrides apply to, or the special wildcard `*` that applies to all targets. The values within the `"target_overrides"` section are objects that map configuration parameters, as printed by `mbed compile --conifg`, to new values. See the example `"target_overrides"` section below. ```JSON "target_overrides": { @@ -126,7 +126,7 @@ The order in which overrides are considered is: #### Defining configuration parameters -The configuration system understands configuration parameters that targets, libraries and applications define. A JSON object called "config" always defines the configuration parameters. +The configuration system understands configuration parameters that targets, libraries and applications define using a JSON object called "config". For example: @@ -149,14 +149,14 @@ For example: You define a configuration parameter by specifying its name as the key and specifying its value either with a description object or by value. The JSON fragment above defines three configuration parameters named `param1`, `param2` and `param3`. -Above, the configuration parameters `param1` and `param2` are defined using a description object. The following keys are supported on the description object: +Above, the configuration parameters `param1` and `param2` are defined using a description object. The description object supports the following keys: - `help`: an optional help message that describes the purpose of the parameter. - `value`: an optional field that defines the value of the parameter. - - `required`: an optional key that specifies whether the parameter must be given a value before compiling the code (`false` by default). It's not possible to compile a source tree with one or more required parameters that don't have a value. Generally, setting `required` to true is only useful when `value` is not set. + - `required`: an optional key that specifies whether the parameter must have a value before compiling the code (`false` by default). It's not possible to compile a source tree with one or more required parameters that don't have a value. Generally, setting `required` to true is only useful when `value` is not set. - `macro_name`: an optional name for the macro defined at compile time for this configuration parameter. The configuration system automatically figures out the corresponding macro name for a configuration parameter, but the user can override this automatically computed name by specifying `macro_name`. -You define a macro by value by using an integer or string instead of the description object, such as `param3` above. Defining a parameter by value is equivalent to a configuration parameter defined with a description object with the key `value` set to the value in place of the description object, the key `help` unset, the key `macro_name` unset, and the key `required` set to `false`. +You define a macro by value by using an integer or string instead of the description object, such as `param3` above. Defining a parameter by value is equivalent to defining it with a description object with the key `value` set to the value in place of the description object, the key `help` not set, the key `macro_name` not set and the key `required` set to `false`. Defining a parameter by value is equivalent to a configuration parameter defined with a description object with the key `value` set to the value in place of the description object, the key `help` unset, the key `macro_name` unset, and the key `required` set to `false`. **Note:** The name of a parameter in `config` can't contain a dot (`.`) character. @@ -215,12 +215,12 @@ In this JSON file: - `name` is the name of the library. **This is a required field.** - `config` defines the configuration parameters of the library, as the section about [defining configuration parameters](#defining-configuration-parameters) explains. -- `macros` is a list of extra macros that are defined when compiling a application that includes this library. A macro can be defined without a value (such as `MYMOD_MACRO1` above) or with a value (such as `MYMOD_MACRO2` above). +- `macros` is a list of extra macros that are defined when compiling a application that includes this library. `macros` defines the provided list of C preprocessor macros. - `target_overrides` is a dictionary with target-specific values for the configuration parameters. All configuration parameters defined in `mylib` have a `mylib.` prefix. In `mbed_app.json`, `buffer_size` is accessible using the name `mylib.buffer_size`. -Use `target_overrides` to override the values of the parameters, depending on the current compilation target. The keys in `target_overrides` are matched against target labels. (You can find a description of Mbed targets in our documentation about [adding and configuring targets](/docs/development/tools/adding-and-configuring-targets.html).) If a key inside `target_overrides` matches one of the target labels, the parameter values change according to the value of the key. +Use `target_overrides` to override the values of the parameters, depending on the current compilation target. The configuration system matches keys in `target_overrides` against target labels. (You can find a description of Mbed targets in our documentation about [adding and configuring targets](/docs/development/tools/adding-and-configuring-targets.html).) If a key inside `target_overrides` matches one of the target labels, the parameter values change according to the value of the key. It is an error for `mbed_lib.json` to override configuration parameters that were not defined. @@ -236,7 +236,7 @@ It is an error to both add and subtract the same value from a cumulative attribu ### `mbed_app.json` Specification -`mbed_app.json` may be present at the root of your application or specified as the argument to the `--app-config` parameter. Unlike library configuration, only one `mbed_app.json` is interpreted during `mbed compile` or `mbed export`. Like `mbed_lib.json`, `mbed_app.json` is a JSON formatted document that contains a root JSON Object. The keys within this object are sections. The allowed sections and their meanings are below: +`mbed_app.json` may be present at the root of your application or specified as the argument to the `--app-config` parameter. The configuration system interprets only one `mbed_app.json` during `mbed compile` or `mbed export`, unlike library configuration. Like `mbed_lib.json`, `mbed_app.json` is a JSON formatted document that contains a root JSON Object. The keys within this object are sections. The allowed sections and their meanings are below: | Section | Required | Meaning | | ------- | -------- | ------- | @@ -273,4 +273,4 @@ The `mbed_app.json` above defines its own configuration parameter (`welcome_stri - When compiling for `NCS36510`, `app.welcome_string` is `"Hello!"`, `target.mac_addr_high` is `"0x11223344"` (from the `NCS36510` override) and `mylib.timer_period` is 100 (from the `*` override). - When compiling for `LPC1768`, `app.welcome_string` is `"Hello!"` and `mylib.timer_period` is 100 (also from the `*` override). -It is an error for the application configuration to override configuration parameters that were not defined. +It is an error for the application configuration to override an undefined configuration parameter. From 9142e954d40f704174b2ce8e82fbc5ce99f67ad9 Mon Sep 17 00:00:00 2001 From: Jimmy Brisson Date: Wed, 28 Mar 2018 15:07:39 -0500 Subject: [PATCH 19/21] Resolve Brian's review comments --- docs/reference/configuration/Connectivity.md | 2 +- docs/reference/configuration/Drivers.md | 2 +- docs/reference/configuration/Platform.md | 2 +- docs/reference/configuration/RTOS.md | 2 +- docs/reference/configuration/configuration.md | 14 +++++++------- 5 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/reference/configuration/Connectivity.md b/docs/reference/configuration/Connectivity.md index 44ecbb16ce..3a1ae19a2b 100644 --- a/docs/reference/configuration/Connectivity.md +++ b/docs/reference/configuration/Connectivity.md @@ -1,7 +1,7 @@

Connectivity

-You can configure various parameters using either C++ APIs or the Arm Mbed configuration system. The following is the complete list of Connectivity configuration parameters, as generated by `mbed compile --config -v`. Please see [the Configuration system documentation](/docs/development/reference/configuration.html) for details on how you may use or override these settings. +You can configure various parameters using either C++ APIs or the Arm Mbed configuration system. The following is the complete list of connectivity configuration parameters, as generated by `mbed compile --config -v`. Please see [the configuration system documentation](/docs/development/reference/configuration.html) for details on how you may use or override these settings. ``` Configuration parameters diff --git a/docs/reference/configuration/Drivers.md b/docs/reference/configuration/Drivers.md index e3e3bd7ad0..4ea1f65bfa 100644 --- a/docs/reference/configuration/Drivers.md +++ b/docs/reference/configuration/Drivers.md @@ -1,6 +1,6 @@

Drivers

-The following is the complete list of driver configuration parameters, as generated by `mbed compile --config -v`. Please see [the Configuration system documentation](/docs/development/reference/configuration.html) for details on how you may use or override these settings. +The following is the complete list of driver configuration parameters, as generated by `mbed compile --config -v`. Please see [the configuration system documentation](/docs/development/reference/configuration.html) for details on how you may use or override these settings. ``` Configuration parameters diff --git a/docs/reference/configuration/Platform.md b/docs/reference/configuration/Platform.md index 42a5b4fe42..8562352350 100644 --- a/docs/reference/configuration/Platform.md +++ b/docs/reference/configuration/Platform.md @@ -1,6 +1,6 @@

Platform

-The following is the complete list of platform configuration parameters, as generated by `mbed compile --config -v`. Please see [the Configuration system documentation](/docs/development/reference/configuration.html) for details on how you may use or override these settings. +The following is the complete list of platform configuration parameters, as generated by `mbed compile --config -v`. Please see [the configuration system documentation](/docs/development/reference/configuration.html) for details on how you may use or override these settings. ``` Configuration parameters diff --git a/docs/reference/configuration/RTOS.md b/docs/reference/configuration/RTOS.md index c114bd3467..be5cd380bf 100644 --- a/docs/reference/configuration/RTOS.md +++ b/docs/reference/configuration/RTOS.md @@ -9,7 +9,7 @@ All threads in Mbed OS share a global heap. By default, mbed OS dynamically allo By default, there are four threads running after boot: the ISR/scheduler thread, the idle thread, the timer thread and the main application thread. Combined, the idle thread, timer thread and ISR/scheduler thread consume 2 kilobytes of RAM. The user cannot modify these. You can expand or reduce the size of the main application thread stack by using the Mbed configuration system. -The following is the complete list of RTOS configuration parameters, as generated by `mbed compile --config -v`. Please see [the Configuration system documentation](/docs/development/reference/configuration.html) for details on how you may use or override these settings. +The following is the complete list of RTOS configuration parameters, as generated by `mbed compile --config -v`. Please see [the configuration system documentation](/docs/development/reference/configuration.html) for details on how you may use or override these settings. ``` Configuration parameters diff --git a/docs/reference/configuration/configuration.md b/docs/reference/configuration/configuration.md index 57c8ee9fe3..c661fb25b8 100644 --- a/docs/reference/configuration/configuration.md +++ b/docs/reference/configuration/configuration.md @@ -156,7 +156,7 @@ Above, the configuration parameters `param1` and `param2` are defined using a de - `required`: an optional key that specifies whether the parameter must have a value before compiling the code (`false` by default). It's not possible to compile a source tree with one or more required parameters that don't have a value. Generally, setting `required` to true is only useful when `value` is not set. - `macro_name`: an optional name for the macro defined at compile time for this configuration parameter. The configuration system automatically figures out the corresponding macro name for a configuration parameter, but the user can override this automatically computed name by specifying `macro_name`. -You define a macro by value by using an integer or string instead of the description object, such as `param3` above. Defining a parameter by value is equivalent to defining it with a description object with the key `value` set to the value in place of the description object, the key `help` not set, the key `macro_name` not set and the key `required` set to `false`. Defining a parameter by value is equivalent to a configuration parameter defined with a description object with the key `value` set to the value in place of the description object, the key `help` unset, the key `macro_name` unset, and the key `required` set to `false`. +You define a macro by value by using an integer or string instead of the description object, such as `param3` above. Defining a parameter by value is equivalent to a configuration parameter defined with a description object with the key `value` set to the value in place of the description object, the key `help` unset, the key `macro_name` unset, and the key `required` set to `false`. **Note:** The name of a parameter in `config` can't contain a dot (`.`) character. @@ -175,7 +175,7 @@ The configuration system appends a prefix to the name of each parameter, so a pa | Section | Required | Meaning | | ------- | -------- | ------- | | `name` | Yes | Name of the library. Must be unique. May not be `app` or `target`.| -| `macros` | No | List of macros to define on the command-line. | +| `macros` | No | List of macros to define in `mbed_config.h`. | | `config` | No | Configuration parameters defined for use in this library. | | `target_overrides` | No | Overrides for target configuration parameters and configuration parameters of the current library. | @@ -215,14 +215,14 @@ In this JSON file: - `name` is the name of the library. **This is a required field.** - `config` defines the configuration parameters of the library, as the section about [defining configuration parameters](#defining-configuration-parameters) explains. -- `macros` is a list of extra macros that are defined when compiling a application that includes this library. `macros` defines the provided list of C preprocessor macros. +- `macros` is a list of extra C preprocessor macros that are defined when compiling an application that includes this library. - `target_overrides` is a dictionary with target-specific values for the configuration parameters. All configuration parameters defined in `mylib` have a `mylib.` prefix. In `mbed_app.json`, `buffer_size` is accessible using the name `mylib.buffer_size`. Use `target_overrides` to override the values of the parameters, depending on the current compilation target. The configuration system matches keys in `target_overrides` against target labels. (You can find a description of Mbed targets in our documentation about [adding and configuring targets](/docs/development/tools/adding-and-configuring-targets.html).) If a key inside `target_overrides` matches one of the target labels, the parameter values change according to the value of the key. -It is an error for `mbed_lib.json` to override configuration parameters that were not defined. +It is an error for `mbed_lib.json` to override an undefined configuration parameter. #### Overriding target attributes @@ -232,16 +232,16 @@ Target configurations contain a set of attributes that you may manipulate with c "target.features_add": ["IPV4"] ``` -It is an error to both add and subtract the same value from a cumulative attribute. For a list of the attributes that you may overwrite, please see our documentation about [adding and configuring targets](/docs/development/tools/adding-and-configuring-targets.html) +It is an error to both add and subtract the same value from a cumulative attribute. For a list of the attributes that you may overwrite, please see our documentation about [adding and configuring targets](/docs/development/tools/adding-and-configuring-targets.html). ### `mbed_app.json` Specification -`mbed_app.json` may be present at the root of your application or specified as the argument to the `--app-config` parameter. The configuration system interprets only one `mbed_app.json` during `mbed compile` or `mbed export`, unlike library configuration. Like `mbed_lib.json`, `mbed_app.json` is a JSON formatted document that contains a root JSON Object. The keys within this object are sections. The allowed sections and their meanings are below: +`mbed_app.json` may be present at the root of your application or specified as the argument of the `--app-config` parameter to `mbed compile` and `mbed e}xort`. The configuration system interprets only one `mbed_app.json` during `mbed compile` or `mbed export`, unlike library configuration. Like `mbed_lib.json`, `mbed_app.json` is a JSON formatted document that contains a root JSON Object. The keys within this object are sections. The allowed sections and their meanings are below: | Section | Required | Meaning | | ------- | -------- | ------- | | `artifact_name` | No | The name for the executable to generate. Defaults to the name of the containing directory. | -| `macros` | No | List of macros to define on the command-line. | +| `macros` | No | List of macros to define in `mbed_config.h`. | | `config` | No | Configuration parameters defined for use in this library. | | `target_overrides` | No | Overrides for target, library and application configuration parameters. | From 6ee151adc4bb882445250306c937594a3b35b922 Mon Sep 17 00:00:00 2001 From: Jimmy Brisson Date: Wed, 28 Mar 2018 15:57:23 -0500 Subject: [PATCH 20/21] Fix crazy typo --- docs/reference/configuration/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/configuration/configuration.md b/docs/reference/configuration/configuration.md index c661fb25b8..f627d2a823 100644 --- a/docs/reference/configuration/configuration.md +++ b/docs/reference/configuration/configuration.md @@ -236,7 +236,7 @@ It is an error to both add and subtract the same value from a cumulative attribu ### `mbed_app.json` Specification -`mbed_app.json` may be present at the root of your application or specified as the argument of the `--app-config` parameter to `mbed compile` and `mbed e}xort`. The configuration system interprets only one `mbed_app.json` during `mbed compile` or `mbed export`, unlike library configuration. Like `mbed_lib.json`, `mbed_app.json` is a JSON formatted document that contains a root JSON Object. The keys within this object are sections. The allowed sections and their meanings are below: +`mbed_app.json` may be present at the root of your application or specified as the argument of the `--app-config` parameter to `mbed compile` and `mbed export`. The configuration system interprets only one `mbed_app.json` during `mbed compile` or `mbed export`, unlike library configuration. Like `mbed_lib.json`, `mbed_app.json` is a JSON formatted document that contains a root JSON Object. The keys within this object are sections. The allowed sections and their meanings are below: | Section | Required | Meaning | | ------- | -------- | ------- | From 44c1cce1d5e48ed73cab3c730497fdea3e640f63 Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Thu, 29 Mar 2018 14:16:36 -0500 Subject: [PATCH 21/21] Delete sentence in configuration.md Delete sentence based on comment response. --- docs/reference/configuration/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/configuration/configuration.md b/docs/reference/configuration/configuration.md index f627d2a823..110f1f1d5c 100644 --- a/docs/reference/configuration/configuration.md +++ b/docs/reference/configuration/configuration.md @@ -34,7 +34,7 @@ events.shared-stacksize = 1024 (macro name: "MBED_CONF_EVENTS_SHARED_STACKSIZE") ``` -You may find that configuration naming does not always describe the parameter's purpose adequately. Use the `-v` switch to include the help text defined with the configuration parameter, where the value of the configuration parameter is defined, and other details. The command `mbed compile --config -v` in the same application as above prints: +Use the `-v` switch to include the help text defined with the configuration parameter, where the value of the configuration parameter is defined, and other details. The command `mbed compile --config -v` in the same application as above prints: ``` Configuration parameters