Merge pull request #327 from autopulated/app-config

Implement app-specific config

Author: autopulated

docs/_layouts/default.html

@@ -47,6 +47,7 @@
             <li data-section="reference/module"><a href="{{ site.github.url }}/reference/module.html">module.json</a></li>
             <li data-section="reference/target"><a href="{{ site.github.url }}/reference/target.html">target.json</a></li>
             <li data-section="reference/ignore"><a href="{{ site.github.url }}/reference/ignore.html">.yotta_ignore</a></li>
+            <li data-section="reference/config"><a href="{{ site.github.url }}/reference/config.html">Config System</a></li>
           </ul>
         </div>
         <div class="col-sm-9">

docs/assets/css/docs.css

@@ -45,14 +45,14 @@ p{
 
 #menu {
   min-height: 800px;
-  width: 200px;
+  width: 180px;
 }
 @media (min-width: 1200px) {
-  width: 200px;
+  width: 180px;
 }
 @media (max-width: 979px) and (min-width: 768px) {
   #menu {
-    width: 200px;
+    width: 180px;
   }
 }
 @media (max-width: 768px) {
@@ -74,8 +74,8 @@ p{
   margin-bottom: 7px;
 }
 #menu li a {
-  padding-top: 8px;
-  padding-bottom: 8px;
+  padding-top: 6px;
+  padding-bottom: 6px;
 }
 #menu li a {
   color: #999;

docs/reference/commands.md

@@ -1,6 +1,6 @@
 ---
 layout: default
-title: Yotta Command Reference
+title: yotta Command Reference
 section: reference/commands
 ---
 
@@ -327,7 +327,7 @@ To link a module you need to perform two steps. First, in the directory of the d
 yotta link
 ```
 
-This will ensure it has all of its own dependencies installed, and then create a symlink from the global modules directory to the current module.
+This will create a symlink from the global modules directory to the current module.
 
 Then, in the module that you would like to use the linked version of the dependency, run:
 
@@ -344,9 +344,10 @@ When you run `yotta link`, links are created in a system-wide directory under
 `YOTTA_PREFIX`, and the links in that directory are then picked up by
 subsequent `yotta link <modulename>` commands.
 
-On linux this defaults to `/usr/local`, and on windows to
-`%PROGRAMFILES/yotta`. To change this directory (e.g. to make yotta link things
-into your home directory), set the `YOTTA_PREFIX` environment variable.
+On linux this defaults to `/usr/local`, and on windows to the python
+installation directory (normally `c:\Python27`). To change this directory (e.g.
+to make yotta link things into your home directory), set the `YOTTA_PREFIX`
+environment variable.
 
 
 <a name="yotta-link-target"></a>
@@ -436,3 +437,27 @@ occurs in, instead of just once.
 `module.json` files, it can make no warranties about whether modules contain
 code under other licenses that have not been declared.
 
+<a name="yotta-config"></a>
+## yotta config
+
+#### Synopsis
+
+```
+yotta config
+```
+
+#### Description
+Display the merged [config data](/reference/config.html) for the current target
+(and application, if the current module defines an executable application).
+
+The config data is produced by merging the json config data defined by the
+application, the current target, and any targets the current target inherits
+from recursively. Values defined by the application will override those defined
+at the same path by targets, and values defined in targets will override values
+defined by targets they inherit from.
+
+The config data displayed is identical to the data that will be available to
+modules when they are built.
+
+See the [config system reference](/reference/config.html) for more details.
+

docs/reference/config.md

@@ -0,0 +1,255 @@
+---
+layout: default
+title: yotta Configuration System Reference
+section: reference/config
+---
+
+# Configuration System Reference
+
+**NOTE: The configuration system is currently experimental. Some of the
+behaviour described below may change in backwards-icompatible ways with minor
+updates to yotta.**
+
+yotta provides a flexible configuration system that can be used to control how
+modules are built based on information provided by [target
+descriptions](/tutorial/targets.html), optionally extended by a `config.json`
+file in the application.
+
+This configuration information can be used to control a module's dependencies,
+and is also made available to code.
+
+<a name="defining"></a>
+## Defining Configuration Data
+Configuration data is defined in two places: [target descriptions](/tutorial/targets.html), and
+[executable applications](/tutorial/tutorial.html#Creating%20an%20Executable).
+
+
+### Target Config Data
+The config data defined by targets can be used to make software modules compile
+across a wide range of different target hardware. For example, it might
+describe things like the frequency of a
+[UART](https://en.wikipedia.org/wiki/Universal_asynchronous_receiver/transmitter)
+serial bus that the target hardware might have for communication.
+
+Software that uses this hardware can then run on different targets, choosing
+the correct frequency to use for the UART communication by reading it from the
+configuration data.
+
+#### Config Data in target.json
+To define config data in a target's target.json file, use the `"config":`
+property, for example:
+
+```json
+{
+    "name":"mytarget",
+    "version":"1.2.3",
+    "license":"Apache-2",
+    "config":{
+        "devices":{
+            "foobar":"value",
+            "volume":11
+        }
+    }
+}
+```
+
+#### Overriding Config Data in Derived Targets
+If a target [inherits](/tutorial/targets.html#inheriting) from a more generic
+target, then the config data in the more-derived target overrides data
+inherited from the base target.
+
+For example, given a base target with config data:
+
+```json
+{
+    "a":{
+        "foo": true,
+        "bar": 123
+    }
+}
+```
+
+And a derived target with config data:
+
+```json
+{
+    "a":{
+        "bar": 456
+    },
+    "b":{
+        "baz": "<whatever>"
+    }
+}
+```
+
+The merged config data (which you can display with the [`yotta
+config`](/reference/commands.html#yotta-config) subcommand), would be:
+
+```json
+{
+    "a":{
+        "foo": true,
+        "bar": 456
+    },
+    "b":{
+        "baz": "<whatever>"
+    }
+}
+```
+
+### Application Config Data
+An executable application may define additional config data to that provided by
+the selected target. To do this, the application should include a file called
+`config.json` alongside its `module.json` file.
+
+The application's configuration data takes highest precedence, so can be used
+to override any values defined by the target data. This is useful for defining
+application-specific configuration, and when developing an application for
+one-off target hardware which is derived from a supported platform (it can
+eliminate the need to define your own target description just for one
+application).
+
+If you find yourself copying & pasting `config.json` data between many
+applications, consider if deriving and publishing [your own
+target](/tutorial/targets.html) would be preferable.
+
+
+### Config Data Syntax
+The yotta config system accepts almost any JSON data, apart from Array objects.
+Array objects are not supported due to the ambiguity of merging inherited array
+objects.
+
+
+<a name="using"></a>
+## Using Configuration Data
+Modules can use the configuration data that has been defined to change their
+behaviour. In general it is best to minimise the amount of configuration that
+your module requires to the absolute minimum possible. This makes it easier
+for people to re-use your module in different applications, and to use it on
+different target hardware, without having to define a lot of configuration.
+
+By convention, modules should only read configuration data from their own
+namespace in the config data, for example a module called `simplelog` might
+read a logging level set in the `simplelog` section of the config data:
+
+```json
+{
+    "mbed":{
+       ...
+    },
+    "simplelog":{
+        "level":1
+    },
+    ...
+}
+```
+
+It would be possible for any other module (say a `betterlog` logging module),
+to read this data and use it to configure itself, but doing so could cause
+things to break if `simplelog` directs its users to do something different with
+the config data than what `betterlog` expects.
+
+**NOTE: support for modules to define schemas on parts of the config data is
+currently being considered. This would formalise the constraints modules have
+on what configuration may be defined.**
+
+### Controlling Dependencies
+
+Config data can be used in the [targetDependencies
+section](/reference/module.html#targetDependencies) of `module.json` files.
+
+If a path in the config data matches the values defined on the left-hand side
+of the targetDependencies hash, then the dependencies declared in the object on
+the right-hand side will be used.
+
+For example, given the config data:
+
+```json
+  {
+     "a": {
+        "enable": true
+     },
+     "b": {
+        "foobar": 123
+     },
+     "c": {
+        "baz": {
+            
+        }
+     },
+     "d": {
+        "etc": "astring"
+     },
+     "e": {
+        "supported": null,
+        "also-falsey": false
+     }
+  }
+```
+
+And the targetDependencies:
+
+```json
+  "targetDependencies": {
+     "a.enable": {
+       "module-1": "^1.2.3"
+     },
+     "b.foobar": {
+       "module-2": "^1.2.3"
+     },
+     "c.baz": {
+       "module-3": "^1.2.3"
+     },
+     "d.etc": {
+       "module-4": "^1.2.3"
+     },
+     "e.supported": {
+       "module-5": "^1.2.3"
+     }
+  }
+```
+
+Then modules 1, 2, 3 and 4 will be included as dependencies, but `module-5` will not.
+
+### Using Configuration In Code
+
+The config data is made available as preprocessor definitions, so that it can
+be tested at compile-time.
+
+For the config data in the above dependencies example, the following
+definitions will be produced:
+
+```C
+#define YOTTA_CFG
+#define YOTTA_CFG_A
+#define YOTTA_CFG_A_ENABLE 1
+#define YOTTA_CFG_B
+#define YOTTA_CFG_B_FOOBAR 123
+#define YOTTA_CFG_C
+#define YOTTA_CFG_C_BAZ
+#define YOTTA_CFG_D
+#define YOTTA_CFG_D_ETC astring
+#define YOTTA_CFG_E
+#define YOTTA_CFG_E_SUPPORTED NULL
+#define YOTTA_CFG_E_ALSO_FALSEY 0
+```
+
+Note that string values are not quoted. If you want a quoted string,
+either embed escaped quotes (`\"`) in the string value, or use the preprocessor
+[stringification
+trick](https://gcc.gnu.org/onlinedocs/cpp/Stringification.html).
+
+JSON boolean values are converted to 1 or 0, and `null` values are converted to `NULL`.
+
+These definitions are defined through a pre-include file called
+`yotta_config.h` which is generated in the root of the build directory.
+
+### Using Configuration in CMakeLists
+
+The config data is also made accessible to any custom CMakeLists.txt that have
+been written to control the build of a module. The CMake definitions are nearly
+the same as the C preprocessor definitions, except that empty definitions, and
+`null` definitions are converted to `set(YOTTA_CFG_<property> "")`, and no
+conversion is performed for boolean values.
+
+

docs/reference/module.md

@@ -220,9 +220,33 @@ The `targetDependencies` property makes this possible.
 Each value in the `targetDependencies` is a target identifier defining a set of
 dependencies with the same format as the [`dependencies`](#dependencies) property.
 
-When calculating the dependencies to install, `yotta` uses the first section
+When calculating the dependencies to install, `yotta` uses all sections
 from `targetDependencies` that matches one of the identifiers in the current
-target's [`similarTo` list](../tutorial/targets.html#similarto).
+target's [`similarTo` list](../tutorial/targets.html#similarto), or which match
+properties that are defined to a truthy value in the [configuration
+data](/reference/config.html).
+
+To test nested values from config data, use dot-syntax,
+`"mbed.meshing.supported"` in the following example tests that the "supported"
+value is truthy in config data that looks like this:
+
+```json
+  {
+    "mbed":{
+      "meshing":{
+        "supported":true
+      }
+    }
+  }
+```
+
+A "truthy" json config value is any object or string, or non-zero numbers, or a
+literal `true` boolean value.
+
+**NOTE: in the future support for evaluating simple expressions on config
+values may be added, but this is not currently possible. To choose which
+one-of-n dependencies to use you must define N config values that are either
+true or false, and require that they are set appropriately.**
 
 Example:
 
@@ -231,6 +255,9 @@ Example:
         "k64f": {
             "mbed-hal-freescale": "^3.0.0",
             "mbed": "^3.0.0"
+        },
+        "mbed.meshing.supported": {
+            "mbed-meshing": "^1.2.3"
         }
 	}
 ```