Magnificent7 / Hackathon

Includes library modifications to allow access to AIN_4 (AIN_0 / 5)

mbd_os/docs/config_system.md@0:eafc3fd41f75, 2016-09-20 (annotated)

Committer:
bryantaylor
Date:
Tue Sep 20 21:26:12 2016 +0000
Revision:
0:eafc3fd41f75
hackathon

Who changed what in which revision?

UserRevisionLine numberNew contents of line
bryantaylor 0:eafc3fd41f75 1 # About the configuration system
bryantaylor 0:eafc3fd41f75 2
bryantaylor 0:eafc3fd41f75 3 The mbed configuration system can be used to customize the compile time configuration of various mbed components (targets, libraries and applications). Each such 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:
bryantaylor 0:eafc3fd41f75 4
bryantaylor 0:eafc3fd41f75 5 - the sampling period for a data acquisition application.
bryantaylor 0:eafc3fd41f75 6 - the default stack size for a newly created OS thread.
bryantaylor 0:eafc3fd41f75 7 - the receive buffer size of a serial communication library.
bryantaylor 0:eafc3fd41f75 8 - the flash and RAM memory size of a mbed target.
bryantaylor 0:eafc3fd41f75 9
bryantaylor 0:eafc3fd41f75 10 The configuration system gathers and interprets all the configuration defined in the source tree. The output of the configuration system is a list of macros that are automatically defined when compiling the code.
bryantaylor 0:eafc3fd41f75 11
bryantaylor 0:eafc3fd41f75 12 # Defining configuration parameters
bryantaylor 0:eafc3fd41f75 13
bryantaylor 0:eafc3fd41f75 14 The configuration system understands configuration data defined in targets, libraries and applications. While 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". An example is given below:
bryantaylor 0:eafc3fd41f75 15
bryantaylor 0:eafc3fd41f75 16 ```
bryantaylor 0:eafc3fd41f75 17 {
bryantaylor 0:eafc3fd41f75 18 "config": {
bryantaylor 0:eafc3fd41f75 19 "param1": {
bryantaylor 0:eafc3fd41f75 20 "help": "The first configuration parameter",
bryantaylor 0:eafc3fd41f75 21 "macro_name": "CUSTOM_MACRO_NAME",
bryantaylor 0:eafc3fd41f75 22 "value": 0
bryantaylor 0:eafc3fd41f75 23 },
bryantaylor 0:eafc3fd41f75 24 "param2": {
bryantaylor 0:eafc3fd41f75 25 "help": "The second configuration parameter",
bryantaylor 0:eafc3fd41f75 26 "required": true
bryantaylor 0:eafc3fd41f75 27 },
bryantaylor 0:eafc3fd41f75 28 "param3": 10
bryantaylor 0:eafc3fd41f75 29 }
bryantaylor 0:eafc3fd41f75 30 }
bryantaylor 0:eafc3fd41f75 31 ```
bryantaylor 0:eafc3fd41f75 32
bryantaylor 0:eafc3fd41f75 33 The JSON fragment above defines 3 configuration parameters named `param1`, `param2` and `param3`. There are two ways to define a configuration parameter:
bryantaylor 0:eafc3fd41f75 34
bryantaylor 0:eafc3fd41f75 35 - the short way: by name and value. `param3` above is an example of a short definition for a parameter named `param3` with value `10`.
bryantaylor 0:eafc3fd41f75 36 - the long way: by name and description (another JSON object), like `param1` and `param2` above. The JSON description object can have the following keys:
bryantaylor 0:eafc3fd41f75 37 - `help`: an optional help message that describes the purpose of the parameter.
bryantaylor 0:eafc3fd41f75 38 - `value`: an optional field that defines the value of the parameter.
bryantaylor 0:eafc3fd41f75 39 - `required`: an optional key that specifies if 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.
bryantaylor 0:eafc3fd41f75 40 - `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`.
bryantaylor 0:eafc3fd41f75 41
bryantaylor 0:eafc3fd41f75 42 Note that the name of a parameter in `config` can't contain a dot (`.`) character.
bryantaylor 0:eafc3fd41f75 43
bryantaylor 0:eafc3fd41f75 44 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:
bryantaylor 0:eafc3fd41f75 45
bryantaylor 0:eafc3fd41f75 46 - **target.** if the parameter is defined in a target.
bryantaylor 0:eafc3fd41f75 47 - **app.** if the parameter is defined in the application.
bryantaylor 0:eafc3fd41f75 48 - the name of the library followed by a dot (.) if the parameter is defined in a library.
bryantaylor 0:eafc3fd41f75 49
bryantaylor 0:eafc3fd41f75 50 # Configuration data in libraries
bryantaylor 0:eafc3fd41f75 51
bryantaylor 0:eafc3fd41f75 52 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 could look like this:
bryantaylor 0:eafc3fd41f75 53
bryantaylor 0:eafc3fd41f75 54 ```
bryantaylor 0:eafc3fd41f75 55 {
bryantaylor 0:eafc3fd41f75 56 "name": "mylib",
bryantaylor 0:eafc3fd41f75 57 "config": {
bryantaylor 0:eafc3fd41f75 58 "buffer_size": 1024,
bryantaylor 0:eafc3fd41f75 59 "timer_period": {
bryantaylor 0:eafc3fd41f75 60 "help": "The timer period (in us)",
bryantaylor 0:eafc3fd41f75 61 "macro_name": "INTERNAL_GPTMR_PERIOD",
bryantaylor 0:eafc3fd41f75 62 "required": true
bryantaylor 0:eafc3fd41f75 63 },
bryantaylor 0:eafc3fd41f75 64 "queue_size": {
bryantaylor 0:eafc3fd41f75 65 "help": "Size of event queue (entries)",
bryantaylor 0:eafc3fd41f75 66 "value": 10
bryantaylor 0:eafc3fd41f75 67 }
bryantaylor 0:eafc3fd41f75 68 },
bryantaylor 0:eafc3fd41f75 69 "macros": ["MYMOD_MACRO1", "MYMOD_MACRO2=\"TEST\""],
bryantaylor 0:eafc3fd41f75 70 "target_overrides": {
bryantaylor 0:eafc3fd41f75 71 "K64F": {
bryantaylor 0:eafc3fd41f75 72 "timer_period": 100,
bryantaylor 0:eafc3fd41f75 73 "queue_size": 40
bryantaylor 0:eafc3fd41f75 74 },
bryantaylor 0:eafc3fd41f75 75 "NXP": {
bryantaylor 0:eafc3fd41f75 76 "queue_size": 20,
bryantaylor 0:eafc3fd41f75 77 "buffer_size": 128
bryantaylor 0:eafc3fd41f75 78 }
bryantaylor 0:eafc3fd41f75 79 }
bryantaylor 0:eafc3fd41f75 80 }
bryantaylor 0:eafc3fd41f75 81 ```
bryantaylor 0:eafc3fd41f75 82
bryantaylor 0:eafc3fd41f75 83 In this JSON file:
bryantaylor 0:eafc3fd41f75 84
bryantaylor 0:eafc3fd41f75 85 - `name` is the name of the library. **This is a required field.**
bryantaylor 0:eafc3fd41f75 86 - `config` defines the configuration parameters of the library, as explained [here](#defining-configuration-parameters).
bryantaylor 0:eafc3fd41f75 87 - `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 (like `MYMOD_MACRO1` above) or with a value (like `MYMOD_MACRO2` above).
bryantaylor 0:eafc3fd41f75 88 - `target_overrides` is a dictionary with target-specific values for the configuration parameters.
bryantaylor 0:eafc3fd41f75 89
bryantaylor 0:eafc3fd41f75 90 `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* (a description of mbed targets can be found [here](mbed_targets.md)). 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:
bryantaylor 0:eafc3fd41f75 91
bryantaylor 0:eafc3fd41f75 92 - `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.
bryantaylor 0:eafc3fd41f75 93 - if the library is compiled for the `K64F` target, `timer_period` will be set to 100 and `queue_size` will be set to 40, since they are overridden by the `K64F` key in `target_overrides`. `buffer_size` will be set to 1024, as defined in `config`.
bryantaylor 0:eafc3fd41f75 94 - 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 neither in `config`, nor in the `NXP` override).
bryantaylor 0:eafc3fd41f75 95 - 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.
bryantaylor 0:eafc3fd41f75 96 - 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`.
bryantaylor 0:eafc3fd41f75 97
bryantaylor 0:eafc3fd41f75 98 Except `name`, all the above keys in the JSON file are optional, but if `target_overrides` is defined, `config` must also be defined.
bryantaylor 0:eafc3fd41f75 99
bryantaylor 0:eafc3fd41f75 100 As explained [here](#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).
bryantaylor 0:eafc3fd41f75 101
bryantaylor 0:eafc3fd41f75 102 If the source tree has code for more than one library, each library needs its own `mbed_lib.json` file in its root folder.
bryantaylor 0:eafc3fd41f75 103
bryantaylor 0:eafc3fd41f75 104 # Configuration data in targets
bryantaylor 0:eafc3fd41f75 105
bryantaylor 0:eafc3fd41f75 106 Like libraries, targets can define their own configuration data. Additionally, tables can override the configuration of the target(s) they inherit from (for more details about how do define a target and target inheritance, check [this link](mbed_targets.md)). Target configuration data is defined in `targets.json` using `config`, as described [here](#defining-configuration-parameters). An example for a hypothetical `Base` target is given below:
bryantaylor 0:eafc3fd41f75 107
bryantaylor 0:eafc3fd41f75 108 ```
bryantaylor 0:eafc3fd41f75 109 "Base": {
bryantaylor 0:eafc3fd41f75 110 "core": "Cortex-M0",
bryantaylor 0:eafc3fd41f75 111 "extra_labels": ["BASE_LABEL"],
bryantaylor 0:eafc3fd41f75 112 "config": {
bryantaylor 0:eafc3fd41f75 113 "serial_console_speed": {
bryantaylor 0:eafc3fd41f75 114 "help": "Baud rate of the serial console",
bryantaylor 0:eafc3fd41f75 115 "value": 115200,
bryantaylor 0:eafc3fd41f75 116 "macro_name": "MBED_SERIAL_UART_SPEED"
bryantaylor 0:eafc3fd41f75 117 },
bryantaylor 0:eafc3fd41f75 118 "stack_size": {
bryantaylor 0:eafc3fd41f75 119 "help": "Initial stack size of the application",
bryantaylor 0:eafc3fd41f75 120 "value": 128
bryantaylor 0:eafc3fd41f75 121 }
bryantaylor 0:eafc3fd41f75 122 }
bryantaylor 0:eafc3fd41f75 123 }
bryantaylor 0:eafc3fd41f75 124 ```
bryantaylor 0:eafc3fd41f75 125
bryantaylor 0:eafc3fd41f75 126 Similar to libraries, the 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`.
bryantaylor 0:eafc3fd41f75 127
bryantaylor 0:eafc3fd41f75 128 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 a `overrides` section. For example:
bryantaylor 0:eafc3fd41f75 129
bryantaylor 0:eafc3fd41f75 130 ```
bryantaylor 0:eafc3fd41f75 131 "Derived": {
bryantaylor 0:eafc3fd41f75 132 "inherits": ["Base"],
bryantaylor 0:eafc3fd41f75 133 "extra_labels_add": ["NXP"],
bryantaylor 0:eafc3fd41f75 134 "config": {
bryantaylor 0:eafc3fd41f75 135 "my_own_config": {
bryantaylor 0:eafc3fd41f75 136 "help": "My very own configuration parameter",
bryantaylor 0:eafc3fd41f75 137 "value": 0
bryantaylor 0:eafc3fd41f75 138 }
bryantaylor 0:eafc3fd41f75 139 },
bryantaylor 0:eafc3fd41f75 140 "overrides": {
bryantaylor 0:eafc3fd41f75 141 "stack_size": 256
bryantaylor 0:eafc3fd41f75 142 }
bryantaylor 0:eafc3fd41f75 143 }
bryantaylor 0:eafc3fd41f75 144 ```
bryantaylor 0:eafc3fd41f75 145
bryantaylor 0:eafc3fd41f75 146 `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:
bryantaylor 0:eafc3fd41f75 147
bryantaylor 0:eafc3fd41f75 148 - 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.
bryantaylor 0:eafc3fd41f75 149 - 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.
bryantaylor 0:eafc3fd41f75 150
bryantaylor 0:eafc3fd41f75 151 It is an error for a derived target to re-define 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.
bryantaylor 0:eafc3fd41f75 152
bryantaylor 0:eafc3fd41f75 153 # Configuration data in applications
bryantaylor 0:eafc3fd41f75 154
bryantaylor 0:eafc3fd41f75 155 Like the configuration for targets and libraries, application configuration is optional; if it exists, it must be defined in a `mbed_app.json` file. Unlike library configuration, there can be a single `mbed_app.json` file in the source tree.
bryantaylor 0:eafc3fd41f75 156
bryantaylor 0:eafc3fd41f75 157 There are quite a few similarities between configuration data in applications and libraries:
bryantaylor 0:eafc3fd41f75 158
bryantaylor 0:eafc3fd41f75 159 - applications define their configuration parameters in the `config` section of `mbed_app.json`, as explained [here](#defining-configuration-parameters).
bryantaylor 0:eafc3fd41f75 160 - 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).
bryantaylor 0:eafc3fd41f75 161 - applications can define macros that will be define at compile time by declaring them in `macros`.
bryantaylor 0:eafc3fd41f75 162
bryantaylor 0:eafc3fd41f75 163 There are also a few differences:
bryantaylor 0:eafc3fd41f75 164
bryantaylor 0:eafc3fd41f75 165 - applications **can't** have a `name` key in `mbed_app.json`. The prefix for the configuration parameters defined in an application is always `app.`.
bryantaylor 0:eafc3fd41f75 166 - applications can also override configuration of libraries and targets in addition to its own configuration in its `target_overrides` section.
bryantaylor 0:eafc3fd41f75 167
bryantaylor 0:eafc3fd41f75 168 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:
bryantaylor 0:eafc3fd41f75 169
bryantaylor 0:eafc3fd41f75 170 ```
bryantaylor 0:eafc3fd41f75 171 {
bryantaylor 0:eafc3fd41f75 172 "config": {
bryantaylor 0:eafc3fd41f75 173 "welcome_string": {
bryantaylor 0:eafc3fd41f75 174 "help": "The string printed on the display on start-up",
bryantaylor 0:eafc3fd41f75 175 "value": "\"Hello!\""
bryantaylor 0:eafc3fd41f75 176 }
bryantaylor 0:eafc3fd41f75 177 },
bryantaylor 0:eafc3fd41f75 178 "target_overrides": {
bryantaylor 0:eafc3fd41f75 179 "*": {
bryantaylor 0:eafc3fd41f75 180 "target.serial_console_speed": 2400,
bryantaylor 0:eafc3fd41f75 181 "mylib.timer_period": 100
bryantaylor 0:eafc3fd41f75 182 },
bryantaylor 0:eafc3fd41f75 183 "Base": {
bryantaylor 0:eafc3fd41f75 184 "target.serial_console_speed": 9600
bryantaylor 0:eafc3fd41f75 185 }
bryantaylor 0:eafc3fd41f75 186 }
bryantaylor 0:eafc3fd41f75 187 }
bryantaylor 0:eafc3fd41f75 188 ```
bryantaylor 0:eafc3fd41f75 189
bryantaylor 0:eafc3fd41f75 190 `target_overrides` works a lot like it does in libraries, but there are a few differences:
bryantaylor 0:eafc3fd41f75 191
bryantaylor 0:eafc3fd41f75 192 - since the application can override any configuration parameter, it must specify them using their prefix (like `mylib.timer_period`). If an overridden parameter doesn't have a prefix, it is assumed that it is one of the parameters defined by the application in its own `config` section.
bryantaylor 0:eafc3fd41f75 193 - 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.
bryantaylor 0:eafc3fd41f75 194
bryantaylor 0:eafc3fd41f75 195 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 (since it matches all targets) and then `Base` is only processed for the `Base` target.
bryantaylor 0:eafc3fd41f75 196
bryantaylor 0:eafc3fd41f75 197 `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`):
bryantaylor 0:eafc3fd41f75 198
bryantaylor 0:eafc3fd41f75 199 - when compiling for `Base`, `app.welcome_string` will be set to `"Hello!"`, `target.serial_console_speed` will be set to 9600 (from the `Base` override) and `mylib.timer_period` will be set to 100 (from the `*` override).
bryantaylor 0:eafc3fd41f75 200 - when compiling for `Derived`, `app.welcome_string` will be set to `"Hello!"`, `target.serial_console_speed` will be set to 2400 (from the `*` override) and `mylib.timer_period` will be set to 100 (also from the `*` override).
bryantaylor 0:eafc3fd41f75 201
bryantaylor 0:eafc3fd41f75 202 It is an error for the application configuration to override configuration parameters that were not defined.
bryantaylor 0:eafc3fd41f75 203
bryantaylor 0:eafc3fd41f75 204 ## Overriding cumulative target attributes
bryantaylor 0:eafc3fd41f75 205
bryantaylor 0:eafc3fd41f75 206 Target configurations contain a set of cumulative attributes that can be manipulated in the application configuration. These attributes can be overriden as a normal configuration parameter, or manipulated with the special `attribute_add` and `attribute_remove` meta-attributes.
bryantaylor 0:eafc3fd41f75 207
bryantaylor 0:eafc3fd41f75 208 Cumulative attributes:
bryantaylor 0:eafc3fd41f75 209 - features: List of features which will be compiled into the resulting binary and available at runtime. Determines the FEATURE directories included during compilation. These are also emitted as FEATURE macros.
bryantaylor 0:eafc3fd41f75 210 - device_has: List of hardware components available on the target. These are emitted as DEVICE_HAS macros.
bryantaylor 0:eafc3fd41f75 211 - extra_labels: List of target labels which determine the TARGET directories included during compilation. These are also emitted as TARGET macros.
bryantaylor 0:eafc3fd41f75 212 - macros: List of target-specific macros that are defined during compilation.
bryantaylor 0:eafc3fd41f75 213
bryantaylor 0:eafc3fd41f75 214 For example, an application may want to remove features with extra space or runtime cost. This `mbed_app.json` will disable the IPV4 network stack. Attempting to use this network stack will result in a compilation error:
bryantaylor 0:eafc3fd41f75 215
bryantaylor 0:eafc3fd41f75 216 ```
bryantaylor 0:eafc3fd41f75 217 {
bryantaylor 0:eafc3fd41f75 218 "target_overrides": {
bryantaylor 0:eafc3fd41f75 219 "K64F": {
bryantaylor 0:eafc3fd41f75 220 "target.features_remove": ["IPV4"]
bryantaylor 0:eafc3fd41f75 221 }
bryantaylor 0:eafc3fd41f75 222 }
bryantaylor 0:eafc3fd41f75 223 }
bryantaylor 0:eafc3fd41f75 224 ```
bryantaylor 0:eafc3fd41f75 225
bryantaylor 0:eafc3fd41f75 226 ## Custom targets
bryantaylor 0:eafc3fd41f75 227
bryantaylor 0:eafc3fd41f75 228 Application configuration can optionally define application-specific targets. These are mbed targets that are needed just to compile this specific application, so it doesn't make sense to add them to the list of official mbed targets; on the contrary, since they're part of `mbed_app.json`, they're versioned together with the application and only known by the application. Application-specific targets are defined with the key `custom_targets` in the `mbed_app.json` file and have the same syntax as a regular target definition, for example:
bryantaylor 0:eafc3fd41f75 229
bryantaylor 0:eafc3fd41f75 230
bryantaylor 0:eafc3fd41f75 231 ```
bryantaylor 0:eafc3fd41f75 232 {
bryantaylor 0:eafc3fd41f75 233 "custom_targets": {
bryantaylor 0:eafc3fd41f75 234 "k64f_myapp": {
bryantaylor 0:eafc3fd41f75 235 "inherits": ["K64F"],
bryantaylor 0:eafc3fd41f75 236 "extra_labels_add": ["CUSTOM_K64F_LIB"]
bryantaylor 0:eafc3fd41f75 237 }
bryantaylor 0:eafc3fd41f75 238 }
bryantaylor 0:eafc3fd41f75 239 }
bryantaylor 0:eafc3fd41f75 240 ```
bryantaylor 0:eafc3fd41f75 241
bryantaylor 0:eafc3fd41f75 242 This will define a new target named `k64f_myapp` that inherits from the `K64F` mbed target, but with an extra label defined, which will change the way the build system looks for sources in the tree.
bryantaylor 0:eafc3fd41f75 243
bryantaylor 0:eafc3fd41f75 244 # Configuration data precedence
bryantaylor 0:eafc3fd41f75 245
bryantaylor 0:eafc3fd41f75 246 The order in which the various bits of configurations are considered is this:
bryantaylor 0:eafc3fd41f75 247
bryantaylor 0:eafc3fd41f75 248 - the configuration defined by an inherited target overrides the configuration defined by its parent(s), as described [above](#configuration-data-in-targets).
bryantaylor 0:eafc3fd41f75 249 - the configuration of the top level application overrides the configuration defined by the target and any of the libraries on which it depends.
bryantaylor 0:eafc3fd41f75 250
bryantaylor 0:eafc3fd41f75 251 For `myapp` above:
bryantaylor 0:eafc3fd41f75 252
bryantaylor 0:eafc3fd41f75 253 - the value of `target.serial_console_speed` will be 9600 when compiling for `Base` because of the `Base` override in myapp's `target_overrides`.
bryantaylor 0:eafc3fd41f75 254 - the value of `target.serial_console_speed` will be 2400 when compiling for any other target because of the `*` override in myapp's `target_overrides`.
bryantaylor 0:eafc3fd41f75 255 - the value of `target.stack_size` will be 256 when compiling for `Derived` and 128 when compiling for `Base` or any other target that derives from `Base` (assuming of course that `Derived` is the only target that redefines `stack_size`).
bryantaylor 0:eafc3fd41f75 256 - the value of `mylib.timer_period` will be 100, since that's overridden by the application and thus takes precedence over the values defined in `mylib`.
bryantaylor 0:eafc3fd41f75 257 - when compiling for `Base`, the values of `mylib.buffer_size` and `mylib.queue_size` will be 1024 and 10 respectively, as defined in the `config` section of `mylib`.
bryantaylor 0:eafc3fd41f75 258 - when compiling for `Derived`, the values of `mylib.buffer_size `and `mylib.queue_size` will be 128 and 20 respectively, since `Derived` defines the `NXP` label and `mylib` defines a specific configuration for this label. Also, since `Derived` has its own `my_own_config` configuration parameter, `target.my_own_config` will also be defined in this case.
bryantaylor 0:eafc3fd41f75 259
bryantaylor 0:eafc3fd41f75 260 # Using configuration data in the code
bryantaylor 0:eafc3fd41f75 261
bryantaylor 0:eafc3fd41f75 262 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 might be different):
bryantaylor 0:eafc3fd41f75 263
bryantaylor 0:eafc3fd41f75 264 ```
bryantaylor 0:eafc3fd41f75 265 // Automatically generated configuration file.
bryantaylor 0:eafc3fd41f75 266 // DO NOT EDIT, content will be overwritten.
bryantaylor 0:eafc3fd41f75 267
bryantaylor 0:eafc3fd41f75 268 #ifndef __MBED_CONFIG_DATA__
bryantaylor 0:eafc3fd41f75 269 #define __MBED_CONFIG_DATA__
bryantaylor 0:eafc3fd41f75 270
bryantaylor 0:eafc3fd41f75 271 // Configuration parameters
bryantaylor 0:eafc3fd41f75 272 #define MBED_CONF_MYAPP_WELCOME_STRING "Hello!" // set by application
bryantaylor 0:eafc3fd41f75 273 #define MBED_SERIAL_UART_SPEED 9600 // set by application[Base]
bryantaylor 0:eafc3fd41f75 274 #define MBED_CONF_TARGET_STACK_SIZE 128 // set by target
bryantaylor 0:eafc3fd41f75 275 #define INTERNAL_GPTMR_PERIOD 100 // set by application[*]
bryantaylor 0:eafc3fd41f75 276 #define MBED_CONF_MYLIB_BUFFER_SIZE 1024 // set by library:mylib
bryantaylor 0:eafc3fd41f75 277 #define MBED_CONF_MYLIB_QUEUE_SIZE 10 // set by library:mylib
bryantaylor 0:eafc3fd41f75 278 // Macros
bryantaylor 0:eafc3fd41f75 279 #define MYMOD_MACRO1 // defined by library:mylib
bryantaylor 0:eafc3fd41f75 280 #define MYMOD_MACRO2 "TEST" // defined by library:mylib
bryantaylor 0:eafc3fd41f75 281
bryantaylor 0:eafc3fd41f75 282 #endif
bryantaylor 0:eafc3fd41f75 283 ```
bryantaylor 0:eafc3fd41f75 284
bryantaylor 0:eafc3fd41f75 285 When compiling for `Derived`, `mbed_config.h` will look like this:
bryantaylor 0:eafc3fd41f75 286
bryantaylor 0:eafc3fd41f75 287
bryantaylor 0:eafc3fd41f75 288 ```
bryantaylor 0:eafc3fd41f75 289 // Automatically generated configuration file.
bryantaylor 0:eafc3fd41f75 290 // DO NOT EDIT, content will be overwritten.
bryantaylor 0:eafc3fd41f75 291
bryantaylor 0:eafc3fd41f75 292 #ifndef __MBED_CONFIG_DATA__
bryantaylor 0:eafc3fd41f75 293 #define __MBED_CONFIG_DATA__
bryantaylor 0:eafc3fd41f75 294
bryantaylor 0:eafc3fd41f75 295 // Configuration parameters
bryantaylor 0:eafc3fd41f75 296 #define MBED_CONF_MYAPP_WELCOME_STRING "Hello!" // set by application
bryantaylor 0:eafc3fd41f75 297 #define MBED_SERIAL_UART_SPEED 2400 // set by application[*]
bryantaylor 0:eafc3fd41f75 298 #define MBED_CONF_TARGET_STACK_SIZE 256 // set by target
bryantaylor 0:eafc3fd41f75 299 #define MBED_CONF_TARGET_MY_OWN_CONFIG 0 // set by target
bryantaylor 0:eafc3fd41f75 300 #define INTERNAL_GPTMR_PERIOD 100 // set by application[*]
bryantaylor 0:eafc3fd41f75 301 #define MBED_CONF_MYLIB_BUFFER_SIZE 128 // set by library:mylib[NXP]
bryantaylor 0:eafc3fd41f75 302 #define MBED_CONF_MYLIB_QUEUE_SIZE 20 // set by library:mylib[NXP]
bryantaylor 0:eafc3fd41f75 303 // Macros
bryantaylor 0:eafc3fd41f75 304 #define MYMOD_MACRO1 // defined by library:mylib
bryantaylor 0:eafc3fd41f75 305 #define MYMOD_MACRO2 "TEST" // defined by library:mylib
bryantaylor 0:eafc3fd41f75 306
bryantaylor 0:eafc3fd41f75 307 #endif
bryantaylor 0:eafc3fd41f75 308 ```
bryantaylor 0:eafc3fd41f75 309
bryantaylor 0:eafc3fd41f75 310 Note that a macro definition will *not* be generated for a parameter that doesn't have a value.
bryantaylor 0:eafc3fd41f75 311
bryantaylor 0:eafc3fd41f75 312 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).
bryantaylor 0:eafc3fd41f75 313
bryantaylor 0:eafc3fd41f75 314 `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.
bryantaylor 0:eafc3fd41f75 315
bryantaylor 0:eafc3fd41f75 316 *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.