[GitHub] ccollins476ad opened a new pull request #260: [RFC] `$import` directive

[GitBox <gi...@apache.org>]

ccollins476ad opened a new pull request #260: [RFC] `$import` directive
URL: https://github.com/apache/mynewt-newt/pull/260
 
 
   ### PROBLEM:
   
   Within a project, there can be a lot of duplication among target `syscfg.yml` files.  The Mynewt package hierarchy mitigates this problem to some extent: the BSP defines some settings, the app overrides a few of those, and the target overrides yet more.  This does not resolve the problem fully, however.  Often, a project has several targets that differ only by one or two syscfg overrides.  For example, a project may have `dev`, `prod`, and `qa` targets, all nearly identical to each other.  Duplicating all the target-level overrides in each target is like any kind of duplication: error prone and a maintenance burden.
   
   ### PROPOSAL:
   
   A new Mynewt keyword: `$import`.  This allows a Mynewt YAML file to import the contents of other YAML files.
   
   Example (`targets/dev/syscfg.yml`):
   
   ```
   $import:
       - 'targets/some_target/syscfg.yml'
       - 'targets/another_target/syscfg.yml'
   
   syscfg.vals:
       OS_DEBUG_MODE: 1
   ```
   
   In this example, the `dev` target's `syscfg.yml` file imports the syscfg files of two other targets.  The target inherits all the setting definitions and values specified in the imported files.
   
   This feature is similar, but not identical, to C's `#include` directive.  Differences between the two features are:
   
   1. Like `#include`, import paths can be absolute or relative.  However, relative paths are always relative to the project base, not to the file doing the importing.
   
   2. The `$import` map can be placed anywhere in the file, but its placement does not affect its behavior.  Imports are always processed before the rest of the file.
   
   3. Unlike `#include`, `$import` does not perform a simple text substitution.  If it did, it would result in an invalid YAML file (multiple `syscfg.defs` or `syscfg.vals` maps).  Instead, maps with the same name are collected from all imported files and merged into the importing file.
   
   ### NOTES
   
   1. This feature introduces the concept of newt keywords.  Keywords are special directives in a YAML file that alter newt's behavior.  Keywords always start with "$".  If newt encounters a keyword that it doesn't understand, it warns the user.
   
   2. This feature may make it confusing to trace down the source of a syscfg override.  Overrides are still a package-level concept, so the `target config` and `target [rev]dep` output indicate which package overrides a setting, not which file.  The implementation of the `$import` feature attaches file info to each syscfg setting (file that defines or overrides the setting along with its import tree), but this information is not accessible at the moment.  I imagine we will want an alternative `target config` command which displays the file performing the override rather than the package.

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services