This is an automated email from the ASF dual-hosted git repository.
ccollins pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/mynewt-core.git
The following commit(s) were added to refs/heads/master by this push:
new faeadf3 docs: Add page for build-time hooks
faeadf3 is described below
commit faeadf339e04281ec26f72fcb95a9e5fa9c82a11
Author: Christopher Collins <ccoll...@apache.org>
AuthorDate: Fri Aug 7 12:44:09 2020 -0700
docs: Add page for build-time hooks
---
docs/os/modules/extcmd/extcmd.rst | 139 ++++++++++++++++++++++++++++++++++++++
docs/os/os_user_guide.rst | 1 +
2 files changed, 140 insertions(+)
diff --git a/docs/os/modules/extcmd/extcmd.rst
b/docs/os/modules/extcmd/extcmd.rst
new file mode 100644
index 0000000..3ee98bf
--- /dev/null
+++ b/docs/os/modules/extcmd/extcmd.rst
@@ -0,0 +1,139 @@
+Build-Time Hooks
+----------------
+
+A package specifies custom commands in its ``pkg.yml`` file. There are
+three types of commands:
+
+1. pre_build_cmds (run before the build)
+2. pre_link_cmds (run after compilation, before linking)
+3. post_build_cmds (run after the build)
+
+Example
+~~~~~~~
+
+Example (apps/blinky/pkg.yml):
+
+.. code-block:: yaml
+
+ pkg.pre_build_cmds:
+ scripts/pre_build1.sh: 100
+ scripts/pre_build2.sh: 200
+
+ pkg.pre_link_cmds:
+ scripts/pre_link.sh: 500
+
+ pkg.post_build_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. All
+paths are relative to the project root.
+
+When newt builds this example, it performs the following sequence:
+
+- scripts/pre_build1.sh
+- scripts/pre_build2.sh
+- [compile]
+- scripts/pre_link.sh
+- [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 build 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 (by path).
+
+All commands are run from the project's base directory. In the above
+example, the ``scripts`` directory is a sibling of ``targets``.
+
+Custom Build Inputs
+~~~~~~~~~~~~~~~~~~~
+
+A custom pre-build or pre-link command can produce files that get fed
+into the current build.
+
+*Pre-build* commands 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.
+
+*Pre-link* commands can only generate .a files.
+
+``.c`` and ``.a`` files should be written to the
+``$MYNEWT_USER_SRC_DIR`` environment variable (defined by newt), 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:
+
+.. code-block:: cpp
+
+ #include "foo/bar.h"
+
+Details
+~~~~~~~
+
+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
Notes
+--------------------------
---------------------------------------------------------------------------------
-------------------------------
+ MYNEWT_APP_BIN_DIR The directory where the current target's binary
gets written.
+ MYNEWT_PKG_BIN_ARCHIVE The path to the current package's ``.a`` file.
+ MYNEWT_PKG_BIN_DIR The directory where the current package's ``.o``
and ``.a`` files get written.
+ MYNEWT_PKG_NAME The full name of the current package.
+ MYNEWT_USER_INCLUDE_DIR Path where globally-accessible headers get
written. Pre-build only.
+ MYNEWT_USER_SRC_DIR Path where build inputs get written.
Pre-build and pre-link only.
+ MYNEWT_USER_WORK_DIR Shared temp directory; used for communication
between commands.
+==========================
=================================================================================
===============================
+
+These environment variables are defined for each process 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):
+
+.. code-block:: yaml
+
+ 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.
+
+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 have changed, they all
+get rebuilt.
+
+The ``$MYNEWT_USER_[...]`` directories are actually temp directories.
+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. The same
+procedure is used for pre-link commands.
+
+Paths
+^^^^^
+
+Custom build inputs get written to the following directories:
+
+- bin/targets/\<target\>/user/pre_build/src
+- bin/targets/\<target\>/user/pre_build/include
+- bin/targets/\<target\>/user/pre_link/src
+
+Custom commands should not write to these directories. They should use
+the ``$MYNEWT_USER_[...]`` environment variables instead.
diff --git a/docs/os/os_user_guide.rst b/docs/os/os_user_guide.rst
index fe5a94b..fd2f3bf 100644
--- a/docs/os/os_user_guide.rst
+++ b/docs/os/os_user_guide.rst
@@ -17,6 +17,7 @@ OS User Guide
Image Manager <modules/imgmgr/imgmgr>
Compile-Time Configuration <modules/sysinitconfig/sysinitconfig>
System Initialization and Shutdown <modules/sysinitdown/sysinitdown>
+ Build-Time Hooks <modules/extcmd/extcmd>
File System <modules/fs/fs>
Flash Circular Buffer <modules/fcb/fcb>
Sensor Framework <modules/sensor_framework/sensor_framework>
