Preliminary main mbed library for nexpaq development

Committer:
nexpaq
Date:
Fri Nov 04 20:27:58 2016 +0000
Revision:
0:6c56fb4bc5f0
Moving to library for sharing updates

Who changed what in which revision?

UserRevisionLine numberNew contents of line
nexpaq 0:6c56fb4bc5f0 1 # About the configuration system
nexpaq 0:6c56fb4bc5f0 2
nexpaq 0:6c56fb4bc5f0 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:
nexpaq 0:6c56fb4bc5f0 4
nexpaq 0:6c56fb4bc5f0 5 - the sampling period for a data acquisition application.
nexpaq 0:6c56fb4bc5f0 6 - the default stack size for a newly created OS thread.
nexpaq 0:6c56fb4bc5f0 7 - the receive buffer size of a serial communication library.
nexpaq 0:6c56fb4bc5f0 8 - the flash and RAM memory size of a mbed target.
nexpaq 0:6c56fb4bc5f0 9
nexpaq 0:6c56fb4bc5f0 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.
nexpaq 0:6c56fb4bc5f0 11
nexpaq 0:6c56fb4bc5f0 12 # Defining configuration parameters
nexpaq 0:6c56fb4bc5f0 13
nexpaq 0:6c56fb4bc5f0 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:
nexpaq 0:6c56fb4bc5f0 15
nexpaq 0:6c56fb4bc5f0 16 ```
nexpaq 0:6c56fb4bc5f0 17 {
nexpaq 0:6c56fb4bc5f0 18 "config": {
nexpaq 0:6c56fb4bc5f0 19 "param1": {
nexpaq 0:6c56fb4bc5f0 20 "help": "The first configuration parameter",
nexpaq 0:6c56fb4bc5f0 21 "macro_name": "CUSTOM_MACRO_NAME",
nexpaq 0:6c56fb4bc5f0 22 "value": 0
nexpaq 0:6c56fb4bc5f0 23 },
nexpaq 0:6c56fb4bc5f0 24 "param2": {
nexpaq 0:6c56fb4bc5f0 25 "help": "The second configuration parameter",
nexpaq 0:6c56fb4bc5f0 26 "required": true
nexpaq 0:6c56fb4bc5f0 27 },
nexpaq 0:6c56fb4bc5f0 28 "param3": 10
nexpaq 0:6c56fb4bc5f0 29 }
nexpaq 0:6c56fb4bc5f0 30 }
nexpaq 0:6c56fb4bc5f0 31 ```
nexpaq 0:6c56fb4bc5f0 32
nexpaq 0:6c56fb4bc5f0 33 The JSON fragment above defines 3 configuration parameters named `param1`, `param2` and `param3`. There are two ways to define a configuration parameter:
nexpaq 0:6c56fb4bc5f0 34
nexpaq 0:6c56fb4bc5f0 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`.
nexpaq 0:6c56fb4bc5f0 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:
nexpaq 0:6c56fb4bc5f0 37 - `help`: an optional help message that describes the purpose of the parameter.
nexpaq 0:6c56fb4bc5f0 38 - `value`: an optional field that defines the value of the parameter.
nexpaq 0:6c56fb4bc5f0 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.
nexpaq 0:6c56fb4bc5f0 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`.
nexpaq 0:6c56fb4bc5f0 41
nexpaq 0:6c56fb4bc5f0 42 Note that the name of a parameter in `config` can't contain a dot (`.`) character.
nexpaq 0:6c56fb4bc5f0 43
nexpaq 0:6c56fb4bc5f0 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:
nexpaq 0:6c56fb4bc5f0 45
nexpaq 0:6c56fb4bc5f0 46 - **target.** if the parameter is defined in a target.
nexpaq 0:6c56fb4bc5f0 47 - **app.** if the parameter is defined in the application.
nexpaq 0:6c56fb4bc5f0 48 - the name of the library followed by a dot (.) if the parameter is defined in a library.
nexpaq 0:6c56fb4bc5f0 49
nexpaq 0:6c56fb4bc5f0 50 # Configuration data in libraries
nexpaq 0:6c56fb4bc5f0 51
nexpaq 0:6c56fb4bc5f0 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:
nexpaq 0:6c56fb4bc5f0 53
nexpaq 0:6c56fb4bc5f0 54 ```
nexpaq 0:6c56fb4bc5f0 55 {
nexpaq 0:6c56fb4bc5f0 56 "name": "mylib",
nexpaq 0:6c56fb4bc5f0 57 "config": {
nexpaq 0:6c56fb4bc5f0 58 "buffer_size": 1024,
nexpaq 0:6c56fb4bc5f0 59 "timer_period": {
nexpaq 0:6c56fb4bc5f0 60 "help": "The timer period (in us)",
nexpaq 0:6c56fb4bc5f0 61 "macro_name": "INTERNAL_GPTMR_PERIOD",
nexpaq 0:6c56fb4bc5f0 62 "required": true
nexpaq 0:6c56fb4bc5f0 63 },
nexpaq 0:6c56fb4bc5f0 64 "queue_size": {
nexpaq 0:6c56fb4bc5f0 65 "help": "Size of event queue (entries)",
nexpaq 0:6c56fb4bc5f0 66 "value": 10
nexpaq 0:6c56fb4bc5f0 67 }
nexpaq 0:6c56fb4bc5f0 68 },
nexpaq 0:6c56fb4bc5f0 69 "macros": ["MYMOD_MACRO1", "MYMOD_MACRO2=\"TEST\""],
nexpaq 0:6c56fb4bc5f0 70 "target_overrides": {
nexpaq 0:6c56fb4bc5f0 71 "K64F": {
nexpaq 0:6c56fb4bc5f0 72 "timer_period": 100,
nexpaq 0:6c56fb4bc5f0 73 "queue_size": 40
nexpaq 0:6c56fb4bc5f0 74 },
nexpaq 0:6c56fb4bc5f0 75 "NXP": {
nexpaq 0:6c56fb4bc5f0 76 "queue_size": 20,
nexpaq 0:6c56fb4bc5f0 77 "buffer_size": 128
nexpaq 0:6c56fb4bc5f0 78 }
nexpaq 0:6c56fb4bc5f0 79 }
nexpaq 0:6c56fb4bc5f0 80 }
nexpaq 0:6c56fb4bc5f0 81 ```
nexpaq 0:6c56fb4bc5f0 82
nexpaq 0:6c56fb4bc5f0 83 In this JSON file:
nexpaq 0:6c56fb4bc5f0 84
nexpaq 0:6c56fb4bc5f0 85 - `name` is the name of the library. **This is a required field.**
nexpaq 0:6c56fb4bc5f0 86 - `config` defines the configuration parameters of the library, as explained [here](#defining-configuration-parameters).
nexpaq 0:6c56fb4bc5f0 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).
nexpaq 0:6c56fb4bc5f0 88 - `target_overrides` is a dictionary with target-specific values for the configuration parameters.
nexpaq 0:6c56fb4bc5f0 89
nexpaq 0:6c56fb4bc5f0 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:
nexpaq 0:6c56fb4bc5f0 91
nexpaq 0:6c56fb4bc5f0 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.
nexpaq 0:6c56fb4bc5f0 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`.
nexpaq 0:6c56fb4bc5f0 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).
nexpaq 0:6c56fb4bc5f0 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.
nexpaq 0:6c56fb4bc5f0 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`.
nexpaq 0:6c56fb4bc5f0 97
nexpaq 0:6c56fb4bc5f0 98 Except `name`, all the above keys in the JSON file are optional, but if `target_overrides` is defined, `config` must also be defined.
nexpaq 0:6c56fb4bc5f0 99
nexpaq 0:6c56fb4bc5f0 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).
nexpaq 0:6c56fb4bc5f0 101
nexpaq 0:6c56fb4bc5f0 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.
nexpaq 0:6c56fb4bc5f0 103
nexpaq 0:6c56fb4bc5f0 104 # Configuration data in targets
nexpaq 0:6c56fb4bc5f0 105
nexpaq 0:6c56fb4bc5f0 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:
nexpaq 0:6c56fb4bc5f0 107
nexpaq 0:6c56fb4bc5f0 108 ```
nexpaq 0:6c56fb4bc5f0 109 "Base": {
nexpaq 0:6c56fb4bc5f0 110 "core": "Cortex-M0",
nexpaq 0:6c56fb4bc5f0 111 "extra_labels": ["BASE_LABEL"],
nexpaq 0:6c56fb4bc5f0 112 "config": {
nexpaq 0:6c56fb4bc5f0 113 "serial_console_speed": {
nexpaq 0:6c56fb4bc5f0 114 "help": "Baud rate of the serial console",
nexpaq 0:6c56fb4bc5f0 115 "value": 115200,
nexpaq 0:6c56fb4bc5f0 116 "macro_name": "MBED_SERIAL_UART_SPEED"
nexpaq 0:6c56fb4bc5f0 117 },
nexpaq 0:6c56fb4bc5f0 118 "stack_size": {
nexpaq 0:6c56fb4bc5f0 119 "help": "Initial stack size of the application",
nexpaq 0:6c56fb4bc5f0 120 "value": 128
nexpaq 0:6c56fb4bc5f0 121 }
nexpaq 0:6c56fb4bc5f0 122 }
nexpaq 0:6c56fb4bc5f0 123 }
nexpaq 0:6c56fb4bc5f0 124 ```
nexpaq 0:6c56fb4bc5f0 125
nexpaq 0:6c56fb4bc5f0 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`.
nexpaq 0:6c56fb4bc5f0 127
nexpaq 0:6c56fb4bc5f0 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:
nexpaq 0:6c56fb4bc5f0 129
nexpaq 0:6c56fb4bc5f0 130 ```
nexpaq 0:6c56fb4bc5f0 131 "Derived": {
nexpaq 0:6c56fb4bc5f0 132 "inherits": ["Base"],
nexpaq 0:6c56fb4bc5f0 133 "extra_labels_add": ["NXP"],
nexpaq 0:6c56fb4bc5f0 134 "config": {
nexpaq 0:6c56fb4bc5f0 135 "my_own_config": {
nexpaq 0:6c56fb4bc5f0 136 "help": "My very own configuration parameter",
nexpaq 0:6c56fb4bc5f0 137 "value": 0
nexpaq 0:6c56fb4bc5f0 138 }
nexpaq 0:6c56fb4bc5f0 139 },
nexpaq 0:6c56fb4bc5f0 140 "overrides": {
nexpaq 0:6c56fb4bc5f0 141 "stack_size": 256
nexpaq 0:6c56fb4bc5f0 142 }
nexpaq 0:6c56fb4bc5f0 143 }
nexpaq 0:6c56fb4bc5f0 144 ```
nexpaq 0:6c56fb4bc5f0 145
nexpaq 0:6c56fb4bc5f0 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:
nexpaq 0:6c56fb4bc5f0 147
nexpaq 0:6c56fb4bc5f0 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.
nexpaq 0:6c56fb4bc5f0 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.
nexpaq 0:6c56fb4bc5f0 150
nexpaq 0:6c56fb4bc5f0 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.
nexpaq 0:6c56fb4bc5f0 152
nexpaq 0:6c56fb4bc5f0 153 # Configuration data in applications
nexpaq 0:6c56fb4bc5f0 154
nexpaq 0:6c56fb4bc5f0 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.
nexpaq 0:6c56fb4bc5f0 156
nexpaq 0:6c56fb4bc5f0 157 There are quite a few similarities between configuration data in applications and libraries:
nexpaq 0:6c56fb4bc5f0 158
nexpaq 0:6c56fb4bc5f0 159 - applications define their configuration parameters in the `config` section of `mbed_app.json`, as explained [here](#defining-configuration-parameters).
nexpaq 0:6c56fb4bc5f0 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).
nexpaq 0:6c56fb4bc5f0 161 - applications can define macros that will be define at compile time by declaring them in `macros`.
nexpaq 0:6c56fb4bc5f0 162
nexpaq 0:6c56fb4bc5f0 163 There are also a few differences:
nexpaq 0:6c56fb4bc5f0 164
nexpaq 0:6c56fb4bc5f0 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.`.
nexpaq 0:6c56fb4bc5f0 166 - applications can also override configuration of libraries and targets in addition to its own configuration in its `target_overrides` section.
nexpaq 0:6c56fb4bc5f0 167
nexpaq 0:6c56fb4bc5f0 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:
nexpaq 0:6c56fb4bc5f0 169
nexpaq 0:6c56fb4bc5f0 170 ```
nexpaq 0:6c56fb4bc5f0 171 {
nexpaq 0:6c56fb4bc5f0 172 "config": {
nexpaq 0:6c56fb4bc5f0 173 "welcome_string": {
nexpaq 0:6c56fb4bc5f0 174 "help": "The string printed on the display on start-up",
nexpaq 0:6c56fb4bc5f0 175 "value": "\"Hello!\""
nexpaq 0:6c56fb4bc5f0 176 }
nexpaq 0:6c56fb4bc5f0 177 },
nexpaq 0:6c56fb4bc5f0 178 "target_overrides": {
nexpaq 0:6c56fb4bc5f0 179 "*": {
nexpaq 0:6c56fb4bc5f0 180 "target.serial_console_speed": 2400,
nexpaq 0:6c56fb4bc5f0 181 "mylib.timer_period": 100
nexpaq 0:6c56fb4bc5f0 182 },
nexpaq 0:6c56fb4bc5f0 183 "Base": {
nexpaq 0:6c56fb4bc5f0 184 "target.serial_console_speed": 9600
nexpaq 0:6c56fb4bc5f0 185 }
nexpaq 0:6c56fb4bc5f0 186 }
nexpaq 0:6c56fb4bc5f0 187 }
nexpaq 0:6c56fb4bc5f0 188 ```
nexpaq 0:6c56fb4bc5f0 189
nexpaq 0:6c56fb4bc5f0 190 `target_overrides` works a lot like it does in libraries, but there are a few differences:
nexpaq 0:6c56fb4bc5f0 191
nexpaq 0:6c56fb4bc5f0 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.
nexpaq 0:6c56fb4bc5f0 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.
nexpaq 0:6c56fb4bc5f0 194
nexpaq 0:6c56fb4bc5f0 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.
nexpaq 0:6c56fb4bc5f0 196
nexpaq 0:6c56fb4bc5f0 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`):
nexpaq 0:6c56fb4bc5f0 198
nexpaq 0:6c56fb4bc5f0 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).
nexpaq 0:6c56fb4bc5f0 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).
nexpaq 0:6c56fb4bc5f0 201
nexpaq 0:6c56fb4bc5f0 202 It is an error for the application configuration to override configuration parameters that were not defined.
nexpaq 0:6c56fb4bc5f0 203
nexpaq 0:6c56fb4bc5f0 204 ## Overriding cumulative target attributes
nexpaq 0:6c56fb4bc5f0 205
nexpaq 0:6c56fb4bc5f0 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.
nexpaq 0:6c56fb4bc5f0 207
nexpaq 0:6c56fb4bc5f0 208 Cumulative attributes:
nexpaq 0:6c56fb4bc5f0 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.
nexpaq 0:6c56fb4bc5f0 210 - device_has: List of hardware components available on the target. These are emitted as DEVICE_HAS macros.
nexpaq 0:6c56fb4bc5f0 211 - extra_labels: List of target labels which determine the TARGET directories included during compilation. These are also emitted as TARGET macros.
nexpaq 0:6c56fb4bc5f0 212 - macros: List of target-specific macros that are defined during compilation.
nexpaq 0:6c56fb4bc5f0 213
nexpaq 0:6c56fb4bc5f0 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:
nexpaq 0:6c56fb4bc5f0 215
nexpaq 0:6c56fb4bc5f0 216 ```
nexpaq 0:6c56fb4bc5f0 217 {
nexpaq 0:6c56fb4bc5f0 218 "target_overrides": {
nexpaq 0:6c56fb4bc5f0 219 "K64F": {
nexpaq 0:6c56fb4bc5f0 220 "target.features_remove": ["IPV4"]
nexpaq 0:6c56fb4bc5f0 221 }
nexpaq 0:6c56fb4bc5f0 222 }
nexpaq 0:6c56fb4bc5f0 223 }
nexpaq 0:6c56fb4bc5f0 224 ```
nexpaq 0:6c56fb4bc5f0 225
nexpaq 0:6c56fb4bc5f0 226 ## Custom targets
nexpaq 0:6c56fb4bc5f0 227
nexpaq 0:6c56fb4bc5f0 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:
nexpaq 0:6c56fb4bc5f0 229
nexpaq 0:6c56fb4bc5f0 230
nexpaq 0:6c56fb4bc5f0 231 ```
nexpaq 0:6c56fb4bc5f0 232 {
nexpaq 0:6c56fb4bc5f0 233 "custom_targets": {
nexpaq 0:6c56fb4bc5f0 234 "k64f_myapp": {
nexpaq 0:6c56fb4bc5f0 235 "inherits": ["K64F"],
nexpaq 0:6c56fb4bc5f0 236 "extra_labels_add": ["CUSTOM_K64F_LIB"]
nexpaq 0:6c56fb4bc5f0 237 }
nexpaq 0:6c56fb4bc5f0 238 }
nexpaq 0:6c56fb4bc5f0 239 }
nexpaq 0:6c56fb4bc5f0 240 ```
nexpaq 0:6c56fb4bc5f0 241
nexpaq 0:6c56fb4bc5f0 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.
nexpaq 0:6c56fb4bc5f0 243
nexpaq 0:6c56fb4bc5f0 244 # Configuration data precedence
nexpaq 0:6c56fb4bc5f0 245
nexpaq 0:6c56fb4bc5f0 246 The order in which the various bits of configurations are considered is this:
nexpaq 0:6c56fb4bc5f0 247
nexpaq 0:6c56fb4bc5f0 248 - the configuration defined by an inherited target overrides the configuration defined by its parent(s), as described [above](#configuration-data-in-targets).
nexpaq 0:6c56fb4bc5f0 249 - the configuration of the top level application overrides the configuration defined by the target and any of the libraries on which it depends.
nexpaq 0:6c56fb4bc5f0 250
nexpaq 0:6c56fb4bc5f0 251 For `myapp` above:
nexpaq 0:6c56fb4bc5f0 252
nexpaq 0:6c56fb4bc5f0 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`.
nexpaq 0:6c56fb4bc5f0 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`.
nexpaq 0:6c56fb4bc5f0 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`).
nexpaq 0:6c56fb4bc5f0 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`.
nexpaq 0:6c56fb4bc5f0 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`.
nexpaq 0:6c56fb4bc5f0 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.
nexpaq 0:6c56fb4bc5f0 259
nexpaq 0:6c56fb4bc5f0 260 # Using configuration data in the code
nexpaq 0:6c56fb4bc5f0 261
nexpaq 0:6c56fb4bc5f0 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):
nexpaq 0:6c56fb4bc5f0 263
nexpaq 0:6c56fb4bc5f0 264 ```
nexpaq 0:6c56fb4bc5f0 265 // Automatically generated configuration file.
nexpaq 0:6c56fb4bc5f0 266 // DO NOT EDIT, content will be overwritten.
nexpaq 0:6c56fb4bc5f0 267
nexpaq 0:6c56fb4bc5f0 268 #ifndef __MBED_CONFIG_DATA__
nexpaq 0:6c56fb4bc5f0 269 #define __MBED_CONFIG_DATA__
nexpaq 0:6c56fb4bc5f0 270
nexpaq 0:6c56fb4bc5f0 271 // Configuration parameters
nexpaq 0:6c56fb4bc5f0 272 #define MBED_CONF_MYAPP_WELCOME_STRING "Hello!" // set by application
nexpaq 0:6c56fb4bc5f0 273 #define MBED_SERIAL_UART_SPEED 9600 // set by application[Base]
nexpaq 0:6c56fb4bc5f0 274 #define MBED_CONF_TARGET_STACK_SIZE 128 // set by target
nexpaq 0:6c56fb4bc5f0 275 #define INTERNAL_GPTMR_PERIOD 100 // set by application[*]
nexpaq 0:6c56fb4bc5f0 276 #define MBED_CONF_MYLIB_BUFFER_SIZE 1024 // set by library:mylib
nexpaq 0:6c56fb4bc5f0 277 #define MBED_CONF_MYLIB_QUEUE_SIZE 10 // set by library:mylib
nexpaq 0:6c56fb4bc5f0 278 // Macros
nexpaq 0:6c56fb4bc5f0 279 #define MYMOD_MACRO1 // defined by library:mylib
nexpaq 0:6c56fb4bc5f0 280 #define MYMOD_MACRO2 "TEST" // defined by library:mylib
nexpaq 0:6c56fb4bc5f0 281
nexpaq 0:6c56fb4bc5f0 282 #endif
nexpaq 0:6c56fb4bc5f0 283 ```
nexpaq 0:6c56fb4bc5f0 284
nexpaq 0:6c56fb4bc5f0 285 When compiling for `Derived`, `mbed_config.h` will look like this:
nexpaq 0:6c56fb4bc5f0 286
nexpaq 0:6c56fb4bc5f0 287
nexpaq 0:6c56fb4bc5f0 288 ```
nexpaq 0:6c56fb4bc5f0 289 // Automatically generated configuration file.
nexpaq 0:6c56fb4bc5f0 290 // DO NOT EDIT, content will be overwritten.
nexpaq 0:6c56fb4bc5f0 291
nexpaq 0:6c56fb4bc5f0 292 #ifndef __MBED_CONFIG_DATA__
nexpaq 0:6c56fb4bc5f0 293 #define __MBED_CONFIG_DATA__
nexpaq 0:6c56fb4bc5f0 294
nexpaq 0:6c56fb4bc5f0 295 // Configuration parameters
nexpaq 0:6c56fb4bc5f0 296 #define MBED_CONF_MYAPP_WELCOME_STRING "Hello!" // set by application
nexpaq 0:6c56fb4bc5f0 297 #define MBED_SERIAL_UART_SPEED 2400 // set by application[*]
nexpaq 0:6c56fb4bc5f0 298 #define MBED_CONF_TARGET_STACK_SIZE 256 // set by target
nexpaq 0:6c56fb4bc5f0 299 #define MBED_CONF_TARGET_MY_OWN_CONFIG 0 // set by target
nexpaq 0:6c56fb4bc5f0 300 #define INTERNAL_GPTMR_PERIOD 100 // set by application[*]
nexpaq 0:6c56fb4bc5f0 301 #define MBED_CONF_MYLIB_BUFFER_SIZE 128 // set by library:mylib[NXP]
nexpaq 0:6c56fb4bc5f0 302 #define MBED_CONF_MYLIB_QUEUE_SIZE 20 // set by library:mylib[NXP]
nexpaq 0:6c56fb4bc5f0 303 // Macros
nexpaq 0:6c56fb4bc5f0 304 #define MYMOD_MACRO1 // defined by library:mylib
nexpaq 0:6c56fb4bc5f0 305 #define MYMOD_MACRO2 "TEST" // defined by library:mylib
nexpaq 0:6c56fb4bc5f0 306
nexpaq 0:6c56fb4bc5f0 307 #endif
nexpaq 0:6c56fb4bc5f0 308 ```
nexpaq 0:6c56fb4bc5f0 309
nexpaq 0:6c56fb4bc5f0 310 Note that a macro definition will *not* be generated for a parameter that doesn't have a value.
nexpaq 0:6c56fb4bc5f0 311
nexpaq 0:6c56fb4bc5f0 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).
nexpaq 0:6c56fb4bc5f0 313
nexpaq 0:6c56fb4bc5f0 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.
nexpaq 0:6c56fb4bc5f0 315
nexpaq 0:6c56fb4bc5f0 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.