You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/advanced_topics/amending_static_inputs.md
+6-4Lines changed: 6 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,10 +3,10 @@
3
3
Occasionally, it may be convenient to declare a static file and then use it as input in the same script.
4
4
As of StepUp 1.2.0, this is allowed and no longer treated as a cyclic dependency.
5
5
6
-
7
6
## Example
8
7
9
-
Create the following `plan.py`, which declares a static file, amends it as input, and then opens it to print it to the standard output.
8
+
Create the following `plan.py`, which declares a static file, amends it as input,
9
+
and then opens it to print it to the standard output.
10
10
11
11
```python
12
12
{% include 'advanced_topics/amending_static_inputs/plan.py'%}
@@ -15,7 +15,9 @@ Create the following `plan.py`, which declares a static file, amends it as input
15
15
Also create a `config.txt` file with some contents.
16
16
17
17
In more realistic scenarios, `config.txt` may be used to decide which steps to add etc.
18
-
For a more elaborate example, take a look at the [`plan.py`](https://github.com/reproducible-reporting/stepup-core/blob/main/docs/plan.py) that is used to run all tutorial examples.
Copy file name to clipboardExpand all lines: docs/advanced_topics/amending_steps.md
+1-3Lines changed: 1 addition & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -43,7 +43,6 @@ This will avoid the following problems:
43
43
To the best of our knowledge, there is no equivalent of `amend()` in other build tools.
44
44
Some features in Ninja cover what can be achieved with `amend()`.
45
45
46
-
47
46
## Example
48
47
49
48
Example source files: [`docs/advanced_topics/amending_steps/`](https://github.com/reproducible-reporting/stepup-core/tree/main/docs/advanced_topics/amending_steps)
@@ -76,7 +75,7 @@ stepup -n 1
76
75
77
76
You should get the following terminal output:
78
77
79
-
```
78
+
```text
80
79
{% include 'advanced_topics/amending_steps/stdout.txt' %}
81
80
```
82
81
@@ -85,7 +84,6 @@ Once this required input becomes clear,
85
84
StepUp schedules the optional step to generate the requested input.
@@ -19,16 +19,18 @@ This can be verified by analyzing the file `converted.txt` or with unit tests.
19
19
20
20
To avoid executing `Step 2` at every iteration in the development of `Step 1`,
21
21
you can **block** this step.
22
-
All step-creating functions accept an optional `block=True` keyword argument to prevent them from being executed.
22
+
All step-creating functions accept an optional `block=True` keyword argument
23
+
to prevent them from being executed.
23
24
Blocking steps is a temporary measure, meant to be reverted once you're done with `Step 1`.
24
25
25
26
Blocking steps has some consequences:
26
27
27
-
- Blocked steps remain in the PENDING state, meaning that outdated output files are not cleaned up automatically.
28
-
- At the end of the *run phase*, a list of blocked steps is shown, to remind the user that some steps are blocked.
28
+
- Blocked steps remain in the `PENDING` state,
29
+
meaning that outdated output files are not cleaned up automatically.
30
+
- At the end of the *run phase*, a list of blocked steps is shown,
31
+
to remind the user that some steps are blocked.
29
32
- Subsequent steps, which use outputs of blocked or pending steps, also remain pending.
30
33
31
-
32
34
## Example
33
35
34
36
Example source files: [`docs/advanced_topics/blocked_steps/`](https://github.com/reproducible-reporting/stepup-core/tree/main/docs/advanced_topics/blocked_steps)
@@ -50,11 +52,10 @@ stepup -n 1
50
52
51
53
You should get the following terminal output:
52
54
53
-
```
55
+
```text
54
56
{% include 'advanced_topics/blocked_steps/stdout.txt' %}
55
57
```
56
58
57
-
58
59
## Try the Following
59
60
60
61
- Unblock the copy step, run StepUp, block it again, and run StepUp again.
Copy file name to clipboardExpand all lines: docs/advanced_topics/environment_variables.md
+5-5Lines changed: 5 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,12 +1,13 @@
1
1
# Environment Variables
2
2
3
3
When defining a step, one can specify the environment variables it uses (not their values).
4
-
When starting StepUp with a different value for any of these variables, StepUp will know that it has to repeat the step instead of skipping it.
4
+
When starting StepUp with a different value for any of these variables,
5
+
StepUp will know that it has to repeat the step instead of skipping it.
5
6
6
-
One can only change an environment variable by stopping StepUp, changing the variable, and then starting StepUp again.
7
+
One can only change an environment variable by stopping StepUp,
8
+
changing the variable, and then starting StepUp again.
7
9
One cannot modify environment variables while StepUp is running.
8
10
9
-
10
11
## Example
11
12
12
13
Example source files: [`docs/advanced_topics/environment_variables/`](https://github.com/reproducible-reporting/stepup-core/tree/main/docs/advanced_topics/environment_variables)
@@ -26,7 +27,7 @@ MYVAR=foo stepup -n 1
26
27
27
28
You will see the following output:
28
29
29
-
```
30
+
```text
30
31
{% include 'advanced_topics/environment_variables/stdout.txt' %}
31
32
```
32
33
@@ -35,7 +36,6 @@ StepUp will not try to substitute `${MYVAR}` before starting the step.
35
36
The special variables `${inp}` and `${out}` are exceptions to this rule,
36
37
as discussed in the [tutorial on dependencies](../getting_started/dependencies.md).
37
38
38
-
39
39
## Try the Following
40
40
41
41
- Repeat `MYVAR=foo stepup -n 1` without making changes.
Copy file name to clipboardExpand all lines: docs/advanced_topics/here_and_root.md
+22-13Lines changed: 22 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,35 +1,42 @@
1
1
# HERE and ROOT variables
2
2
3
-
When a worker runs a step, it defines several environment variables, including `HERE` and `ROOT`, which can be relevant for writing advanced scripts.
4
-
(The workers also define variables starting with `STEPUP_`, but these are only useful to StepUp itself, not to end users.)
3
+
When a worker runs a step, it defines several environment variables,
4
+
including `HERE` and `ROOT`, which can be relevant for writing advanced scripts.
5
+
(The workers also define variables starting with `STEPUP_`,
6
+
but these are only useful to StepUp itself, not to end users.)
5
7
6
8
The two variables are defined as follows:
7
9
8
-
-`HERE` contains the relative path from the directory where StepUp was started to the current working directory of the step.
9
-
-`ROOT` contains the opposite: the relative directory from the current working directory to the directory where StepUp was started.
10
+
-`HERE` contains the relative path from the directory where StepUp was started
11
+
to the current working directory of the step.
12
+
-`ROOT` contains the opposite: the relative directory from the current working directory
13
+
to the directory where StepUp was started.
10
14
11
15
Hence, `HERE/ROOT` and `ROOT/HERE` normalize to the current directory: `./`.
12
16
13
17
These variables can be useful in the following cases:
14
18
15
19
- For out-of-source builds, where you want to replicate the directory structure of the source material.
16
20
(See example below.)
17
-
- To reference a local script that is stored in the top-level directory of your project:`${ROOT}/script.py`
18
-
21
+
- To reference a local script that is stored in the top-level directory of your project:
22
+
`${ROOT}/script.py`
19
23
20
24
## Example
21
25
22
26
Example source files: [`docs/advanced_topics/here_and_root/`](https://github.com/reproducible-reporting/stepup-core/tree/main/docs/advanced_topics/here_and_root)
23
27
24
-
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.
28
+
This example represents a minimal out-of-source build,
29
+
which is nevertheless involving several files,
30
+
due to the inherent complexity of out-of-source builds.
25
31
26
32
Create a `source/` directory with the following `source/plan.py`:
27
33
28
34
```python
29
35
{% include 'advanced_topics/here_and_root/source/plan.py'%}
30
36
```
31
37
32
-
Also create a `source/sub/` directory with a file `source/sub/example.txt` (arbitrary contents) and the following `source/sub/plan.py`:
38
+
Also create a `source/sub/` directory with a file `source/sub/example.txt` (arbitrary contents)
39
+
and the following `source/sub/plan.py`:
33
40
34
41
```python
35
42
{% include 'advanced_topics/here_and_root/source/sub/plan.py'%}
@@ -44,13 +51,15 @@ stepup -n 1
44
51
45
52
You should get the following terminal output:
46
53
47
-
```
54
+
```text
48
55
{% include 'advanced_topics/here_and_root/stdout.txt' %}
49
56
```
50
57
51
-
The top-level `plan.py` provides some infrastructure: some static files and creating the public directory where the outputs will be created.
58
+
The top-level `plan.py` provides some infrastructure:
59
+
some static files and creating the public directory where the outputs will be created.
52
60
53
-
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`.
61
+
The script `sub/plan.py` uses the `ROOT` and `HERE` variables in a way
62
+
that is independent of the location of this `sub/plan.py`.
54
63
It may therefore be fixed in an environment variable, for example:
55
64
56
65
```bash
@@ -70,11 +79,11 @@ StepUp was started and will be translated to the working directory of the script
70
79
[`getenv()`][stepup.core.api.getenv].
71
80
Any variables present in the environment variable will also be substituted once.
72
81
73
-
74
82
## Try the Following
75
83
76
84
- Modify the scripts `plan.py` and `sub/plan.py` to utilize a `DST` variable as explained above.
77
-
To achieve this, define `DST` externally, for instance, by starting StepUp as `DST='../public/${HERE}' stepup -n 1`.
85
+
To achieve this, define `DST` externally, for instance,
86
+
by starting StepUp as `DST='../public/${HERE}' stepup -n 1`.
78
87
79
88
- As a follow-up to the previous point, run StepUp with a different `DST` value.
0 commit comments