aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--doc/rst/usage.rst55
1 files changed, 55 insertions, 0 deletions
diff --git a/doc/rst/usage.rst b/doc/rst/usage.rst
index 01c3411..204de09 100644
--- a/doc/rst/usage.rst
+++ b/doc/rst/usage.rst
@@ -542,6 +542,43 @@ to symbolic links if hard links are not supported. This should be fine in
most cases, but fine-tuning can be done via OVERLAY_DISTDIR_STRATEGY_ and
OVERLAY_DISTDIR_FLAT_.
+------------------
+ roverlay helpers
+------------------
+
+An installation of roverlay includes some helper programs:
+
+*roverlay-sh*
+ a wrapper around /bin/sh that runs a shell or shell script in roverlay's
+ `hook environment`_.
+
+ roverlay-related scripts can use it to automatically inherit roverlay's
+ config and ``$FUNCTIONS`` file:
+
+ .. code-block:: sh
+
+ #!/usr/bin/roverlay-sh
+
+ # reset DEBUG, VERBOSE, QUIET
+ DEBUG=n; QUIET=n; VERBOSE=y
+
+ # load the functions file (optional)
+ . "${FUNCTIONS?}" || exit
+
+ # script body
+ true
+
+ <<TODO: maybe there's a better place for the details>>
+
+
+*name_is_todo--roverlay_creation_helper*
+ <<TODO>>
+ Safely runs overlay creation <<and $$afterwards>>.
+ Suitable for being run as cron job.
+
+
+
+
===============================
Basic Implementation Overview
===============================
@@ -2027,6 +2064,8 @@ the config file. An empty string sets the policy to *deny all*.
+----------------+-------------------+-----------------------------------------+
| ROVERLAY_PHASE | event | event that caused the script to run |
+----------------+-------------------+-----------------------------------------+
+ | OVERLAY_NAME | config | name of the overlay |
+ +----------------+-------------------+-----------------------------------------+
| OVERLAY | config | overlay directory (`OVERLAY_DIR`_), |
+----------------+-------------------+ initial working directory |
| S | *$OVERLAY* | |
@@ -2046,6 +2085,9 @@ the config file. An empty string sets the policy to *deny all*.
+----------------+-------------------+ |
| FILESDIR | *$ADDITIONS_DIR* | |
+----------------+-------------------+-----------------------------------------+
+ | WORKDIR | config | directory for work data |
+ | | | (`CACHEDIR`_) |
+ +----------------+-------------------+-----------------------------------------+
| SHLIB | *$ADDITIONS_DIR*, | A list of directories with shell |
| | *installed?* | function files |
| | | (optional, only set if any dir exists) |
@@ -2053,6 +2095,19 @@ the config file. An empty string sets the policy to *deny all*.
| FUNCTIONS | *$ADDITIONS_DIR*, | file with essential shell functions |
| | *installed?* | (optional, only set if it exists) |
+----------------+-------------------+-----------------------------------------+
+ | DATADIR | *installed?* | location of installed data files |
+ | | | (directory, usually |
+ | | | */usr/share/roverlay*) |
+ +----------------+-------------------+-----------------------------------------+
+ | ROVERLAY\ | sys.argv | path to the roverlay executable that |
+ | _HELPER_EXE | | created the hook environment |
+ | | | (usually */usr/bin/roverlay* or |
+ | | | */usr/bin/roverlay-sh*) |
+ +----------------+-------------------+-----------------------------------------+
+ | ROVERLAY_EXE | guessed, | guessed path to the roverlay "main" |
+ | | *$ROVERLAY\ | executable (which creates the overlay) |
+ | | _HELPER_EXE* | |
+ +----------------+-------------------+-----------------------------------------+
| DEBUG | log level | *shbool* (``y`` or ``n``) that |
| | | indicates whether debug messages should |
| | | be printed |