There is a handful of variables that have special meaning to Space.
How these variables are set will ultimately decide what is exported.
The special variables are called Space variables and they could be set already in the YAML document or using the
-e switch on command line.
Later they could be set and altered in module functions headers or in module functions that act as “build time” functions.
- YAML Variable: Name of the environment variable which is set using
-eswitch and/or in the YAML structure below the
None of these variables are inherited from the shell environment.
- Header Variable: Variable could be set in a functions
space headerat build time. Header Variables are inherited from YAML Variables.
- Header Overwritable: “Yes” means that setting the variable in a
space headerwill overwrite the current value.
“No” means that once it is set it cannot be overridden unless from a
“Append” means that new values will be appended.
- Explanation: Brief summary. Look further below for more in detail explanations.
|YAML Variable||Header Variable||Headers Overwritable||Explanation|
|RUN⁰||SPACE_FN||Yes||RUN is a function name or shell code snippet to run (but only one command, no ‘;’, ‘&&’ or ‘|
|RUN_ALIAS¹²||-||-||Use RUN_ALIAS to point to another node in the YAML structure to load and overlay.|
|SPACE_MUTE_EXIT²||-||-||When SPACE_MUTE_EXIT is set to “1” the exit status of the script will be ignored, returning 0 in all occasions. Meaning that if this is set in YAML (or using -e) to “1”, then the return status of RUN will be ignored.|
|SPACE_ASSERT_EXIT²||-||-||If set, it is the expected return status of the script. If the exit status is not equal to SPACE_ASSERT_EXIT then Space will return 1. Could be set in YAML or using –e flag.|
|-||SPACE_SIGNATURE||-||Defines a function signature describing the expected arguments to help user with validation. Space will exit with error if the signature is not fulfilled. Arguments in brackets are treated as optional. The signature is validated before the other header variables, meaning that one cannot set SPACE_ARGS in the same header and expect SPACE_SIGNATURE to see that. Arguments can provide a minimum and optionally miximum length of values, e.g.
|SPACE_REDIR||SPACE_REDIR||No||Redirect in/out files to the command in the export. It is encouraged to not pass files by their file name into external programs, instead, it is preferable to pipe the file into the program via
|SPACE_ENV||SPACE_ENV||Yes||List of variable names to export with the
|SPACE_ARGS⁵||SPACE_ARGS||Yes||A function can replace or manipulate its arguments using this Space variable. If SPACE_FN is defined then SPACE_ARGS will be the arguments to that next function but not to the build time function defined by the body of the function declaring SPACE_FN (use
|SPACE_DEP||SPACE_DEP||Yes||When a function depends on another function in the same module, or any other loaded module, that dependency must be declared using
|SPACE_WRAP⁴||SPACE_WRAP||Append³||A function that declares this header variable will be wrapped and executed inside the wrap command. A typical use case is to wrap a command in SSH to run it on a remote server, or to wrap it in a “docker exec” to run it inside a Docker container, or both together to run the command over SSH inside a Docker container. The first name in the list is the innermost wrapper and the last name is the outermost wrapper. Default value is taken from
|SPACE_WRAPARGS||SPACE_WRAPARGS||Append³||Arguments to a SPACE_WRAP function. Optional. Multiple entries are newline (\n) separated.|
|SPACE_OUTER⁴||SPACE_OUTER||No||Points to a wrap function that is guaranteed to run locally and wrap the main function. Good for loops and iterating over a local file list, for instance. Only settable from the first level function (not from the wrappers).|
|SPACE_OUTERARGS||SPACE_OUTERARGS||No||Arguments to the SPACE_OUTER function.|
|SPACE_BUILDENV||-||For a function declaring SPACE_FN, it could also declare which environment variables its function body (if any) will be needing.|
|SPACE_BUILDDEP||-||For a function declaring SPACE_FN, it could also declare which function dependencies its function body (if any) has.|
|SPACE_BUILDARGS||-||For a function declaring SPACE_FN, it could also declare which function arguments its function body (if any) will adopt.|
|SPACE_SUDO||-||-||To wrap functions in ‘sudo’ and/or ‘su’. The rightmost item is for the actual command being run which is the innermost wrapped (if any wrappers). Second from right is the next from inner, etc. The leftmost will always be the outer function wrapper (if any). The format is SPACE_SUDO=“sudo:user,:user,sudo,,sudo”. Blanks are permitted to not sudo/su a particular wrapper. To have blanks at the end you will need an extra comma. The cmd line flag
⁰ This variable changes name when entering the
build stage, because it could be a function or a shell snippet when defined in YAML or with
RUNis much shorter to type than
¹ These variables will only be parsed and set from the last part of the node path while other variables will get parsed and set from the top down to the deepest node part giving such variables the ability to be inherited downwards in YAML structures.
² These variables cannot be set from the
space header, but can instead be set by a
build time functionor as an environment variable. They are not inherited from the outer environment.
SPACE_WRAPdeclarations will result in multiple wrappings of the final command.
SPACE_WRAPARGSmust be balanced against each other when manually overriding them using a
⁴ A wrapper function can itself only use
SPACE_FN. If it uses
SPACE_FNit becomes a
SPACE_ARGScan be set in YAML and is then replacing the arguments following the
RUNvariable also defined in YAML. Any command line arguments will either be appended to the argument list or replace any arguments in the list following a
--token. However if the last argument in the argument list is the token
-|then no command line arguments will be appended. The tokens
-|must not be used simultaneously. Both tokens are automatically removed in the final result. Any shell function that defines
SPACE_ARGSwill override whatever was the result from the above haggling.
⁶ Each time this variable is defined in a space header the values are appended and the export is the aggregation of it all.
⁷ A dependency function could itself only declare
space header variable set in a function header must always be set using double quotes:
This is due to restrictions in Space’s own parser. This only applies to header variables set in the header.
The order of which
space header variables are set could be significant.
Previous: Writing your own Space Module
Next: Spacefile YAML referenceEdit this page