HERE and ROOT Variables¶

When a step runs, it defines several environment variables, including ${HERE} and ${ROOT}, which can be relevant for writing advanced scripts. (Steps also have variables starting with STEPUP_, but these are only useful to StepUp itself, not to end users.)

The two variables are defined as follows:

${HERE} is the relative path from the directory where StepUp was started to the step’s working directory.
${ROOT} is the relative path in the opposite direction: from the step’s working directory back to where StepUp was started.

The two are therefore inverse paths, so ${HERE}/${ROOT} and ${ROOT}/${HERE} both normalize to the current directory ./.

These variables can be useful in the following cases:

For out-of-source builds, where you want to replicate the directory structure of the source material. (See example below.)
To reference a local script that is stored in the top-level directory of your project: ${ROOT}/script.py

Example¶

Example source files: docs/advanced_topics/here_and_root/

This example represents a minimal out-of-source build, which is nevertheless involving several files, due to the inherent complexity of out-of-source builds.

Create a source/ directory with the following source/plan.py:

#!/usr/bin/env python3
from stepup.core.api import plan, static

static("sub/plan.py")
plan("./plan.py", workdir="sub")

Also create a source/sub/ directory with a file source/sub/example.txt (arbitrary contents) and the following source/sub/plan.py:

#!/usr/bin/env python3
from stepup.core.api import copy, static

static("example.txt")
copy("example.txt", "${ROOT}/../public/${HERE}/")

Make the scripts executable and run everything as follows:

chmod +x plan.py sub/plan.py
sb -j 1

You should get the following terminal output:

        0/0 |   DIRECTOR │ Listening on /tmp/stepup-########/director (StepUp Core 3.2.3.post54)
        0/0 |    STARTUP │ (Re)initialized boot script
        0/1 |      PHASE │ build
        0/1 |      START │ ./plan.py
        1/2 |    SUCCESS │ ./plan.py
        1/2 |      START │ ./plan.py  # wd=sub
        2/3 |    SUCCESS │ ./plan.py  # wd=sub
        2/3 |      START │ cp -p example.txt ../../public/sub/example.txt  # wd=sub
        3/3 |    SUCCESS │ cp -p example.txt ../../public/sub/example.txt  # wd=sub
        3/3 |   DIRECTOR │ Trying to delete 0 outdated output(s)
        3/3 |   DIRECTOR │ See you!

The top-level plan.py provides some infrastructure: some static files and creating the public directory where the outputs will be created.

The script sub/plan.py uses the ${ROOT} and ${HERE} variables in a way that is independent of the location of this sub/plan.py. It may therefore be fixed in an environment variable, for example:

export DST='../public/${HERE}'

Then you can get this path in any plan.py as follows:

from stepup.core.api import getenv
dst = getenv("DST", back=True)

The back=True option implies that the variable is a path defined globally. If it is a relative path, it will be interpreted relative to the working directory where StepUp was started and will be translated to the working directory of the script calling getenv(). Any variables present in the environment variable will also be substituted once.

Try the Following¶

Modify the scripts plan.py and sub/plan.py to utilize a DST variable as explained above. To achieve this, define DST externally, for instance, by starting StepUp as DST='../public/${HERE}' sb -j 1.
As a follow-up to the previous point, run StepUp with a different DST value. For example: DST='../out/${HERE}' sb -j 1. You will see that all old output files get cleaned up after the new output is created.