Environment Variables

When defining a step, one can specify the environment variables it uses (not their values). When restarting StepUp with a different value for any of these variables, StepUp will know that it has to rerun the step instead of skipping it, even if input files have not changed.

One can only change an environment variable by stopping StepUp, changing the variable, and then starting StepUp again. One cannot modify environment variables while StepUp is running.

Example

Example source files: docs/advanced_topics/environment_variables/

Create the following plan.py:

#!/usr/bin/env python3
from stepup.core.api import runsh

runsh("echo ${MYVAR}", env="MYVAR")

Make it executable and run StepUp with a specific value of the variable:

chmod +x plan.py
MYVAR=foo stepup boot -n 1

You will see the following output:

        0/0 |   DIRECTOR │ Listening on /tmp/stepup-########/director (StepUp 3.0.0)
        0/0 |    STARTUP │ (Re)initialized boot script
        0/0 |   DIRECTOR │ Launched worker 0
        0/1 |      PHASE │ run
        0/1 |      START │ runpy ./plan.py
        1/2 |    SUCCESS │ runpy ./plan.py
        1/2 |      START │ runsh echo ${MYVAR}
        2/2 |    SUCCESS │ runsh echo ${MYVAR}
─────────────────────────────── Standard output ────────────────────────────────
foo
────────────────────────────────────────────────────────────────────────────────
        2/2 |   DIRECTOR │ Trying to delete 0 outdated output(s)
        2/2 |   DIRECTOR │ Stopping workers
        2/2 |   DIRECTOR │ See you!

The variable substitution is performed in the subshell of the worker. StepUp will not try to substitute ${MYVAR} before starting the step. The special variables ${inp} and ${out} are exceptions to this rule, as discussed in the tutorial on dependencies.

Try the Following

• Repeat MYVAR=foo stepup boot -n 1 without making changes. You will see that the echo step is skipped as expected.

• Now run MYVAR=bar stepup boot -n 1. This time, the variable change will cause the step to be executed.

Injecting Environment Variables

Besides working with external environment variables, you can also inject environment variables into the command of a step. For example:

msg = "hello"
runsh(f"MESSAGE={msg} " + "echo ${MESSAGE}")

Note that this is a different mechanism and it practically serves a different purpose. In this case, there is no point in add the argument env="MESSAGE", because this step will not be sensitive to the value of MESSAGE defined outside StepUp.