[GitHub] [mynewt-newt] ccollins476ad opened a new pull request #335: [RFC] Run custom commands at build time

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

ccollins476ad opened a new pull request #335: [RFC] Run custom commands at build time
URL: https://github.com/apache/mynewt-newt/pull/335
 
 
   This PR adds the ability to run custom commands at build time.
   
   A package specifies custom commands in its `pkg.yml` file.  There are two types of commands: 1) pre_cmds (run before the build), and 2) post_cmds (run after the build).
   
   ### EXAMPLE
   
   Example (apps/blinky/pkg.yml):
   ```
   pkg.pre_cmds:
       scripts/pre_build1.sh: 100
       scripts/pre_build2.sh: 200
   
   pkg.post_cmds:
       scripts/post_build.sh: 100
   ```
   
   For each command, the string on the left specifies the command to run.
   The number on the right indicates the command's relative ordering.
   
   When newt builds this example, it performs the following sequence:
   
   * scripts/pre_build1.sh
   * scripts/pre_build2.sh
   * [compile]
   * [link]
   * scripts/post_build.sh
   
   If other packages specify custom commands, those commands would also be executed during the above sequence.  For example, if another package specifies a pre command with an ordering of 150, that command would run immediately after `pre_build1.sh`.  In the case of a tie, the commands are run in lexicographic order.
   
   All commands are run from the project's base directory.  In the above example, the `scripts` directory would be a sibling of `targets`.
   
   ### CUSTOM BUILD INPUTS
   
   A custom pre-build command can produce files that get fed into the current build.  A command can generate any of the following:
   
   1) .c files for newt to compile.
   2) .a files for newt to link.
   3) .h files that any package can include.
   
   .c and .a files should be written to "$MYNEWT_USER_SRC_DIR" (or any subdirectory within).
   
   .h files should be written to "$MYNEWT_USER_INCLUDE_DIR".  The directory structure used here is directly reflected by the includer.  E.g., if a script writes to:
   ```
   $MYNEWT_USER_INCLUDE_DIR/foo/bar.h
   ```
   
   then a source file can include this header with:
   ```
   #include "foo/bar.h"
   ```
   
   ### DETAILS
   
   #### 1. Environment variables
   
   In addition to the usual environment variables defined for debug and download scripts, newt defines the following env vars for custom commands:
   
   | Environment variable    | Description |
   |-------------------------|-------------|
   | MYNEWT_USER_SRC_DIR     | Path where build inputs get written. |
   | MYNEWT_USER_INCLUDE_DIR | Path where globally-accessible headers get written. |
   | MYNEWT_PKG_NAME         | The full name of the package that specifies the command being executed. |
   | MYNEWT_APP_BIN_DIR      | The path where the current target's binary gets written. |
   
   These environment variables are defined for each processes that a custom command runs in.  They are *not* defined in the newt process itself.  So, the following snippet will not produce the expected output:
   
   BAD Example (apps/blinky/pkg.yml):
   ```
   pkg.pre_cmds:
       'echo $MYNEWT_USER_SRC_DIR': 100
   ```
   
   You can execute `sh` here instead if you need access to the environment variables, but it is probably saner to just use a script.
   
   #### 2. Detect changes in custom build inputs
   
   To avoid unnecessary rebuilds, newt detects if custom build inputs have changed since the previous build.  If none of the inputs have changed, then they do not get rebuilt.  If any of them of them have changed, they all get rebuilt.
   
   The $MYNEWT_USER_[...] base is actually a temp directory.  After the pre-build commands have run, newt compares the contents of the temp directory with those of the actual user directory.  If any differences are detected, newt replaces the user directory with the temp directory, triggering a rebuild of its contents.
   
   #### 3. Paths
   
   Custom build inputs get written to the following directories:
   
   * bin/targets/<target>/user/src
   * bin/targets/<target>/user/include
   
   Custom commands should not write to these directories.  They should use the $MYNEWT_USER_[...] environment variables instead.

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to 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