A path through this book¶

Filenames keep a number so the source tree sorts. That number is not a reading order. This page is the curriculum: hour-sized levels, prerequisite edges named. A reader arrives with a task. The map can be entered at any point. The book is three parts, each a page:

Part	For
The recipe	the file and the build
The stack	a tree on a machine that may not have built it
The test	four kinds of testing, then ReFrame

Levels below are hour-sized entries into those parts. Numbering is not the curriculum.

By task¶

Task	Read
a build just failed	Reading a failed build
a module will not load	The robot and What “installed” means
a recipe for software that has none	Writing one from nothing
a port from conda-forge or Spack	eb-stack ports a recipe and bumps one
a stack on a machine with none	EESSI, somebody else’s stack
a ReFrame test of an installed module	A ReFrame test is a class
EasyBuild is the wrong tool	the afterword

The recipe¶

Level A. Read a recipe¶

One hour. No installations are present and no configuration is required.

Read	For
the tutorial	predicting what EasyBuild will do with a file
An easyconfig is Python	why the file is Python, and what that costs
A toolchain is a hierarchy	which dependencies a toolchain permits

Finally, an easyconfig can be read aloud. What it will download, which easyblock it will search for, and which dependencies it may use.

Level B. Understand why a build fails¶

Two hours, and the level where most support tickets reside. Requires level A.

Read	For
A pin is for one generation	why a version is a pin and not a floor
The robot	what `--robot` resolves, and in what order
A versionsuffix is part of the name	why a suffix is identity
What “installed” means	what a sanity check asserts
A checksum is a claim about bytes	what a checksum does and does not promise

Level C. Work on a machine¶

Estimated time: two hours. Requires level A; level B speeds it up.

Read	For
Reading a failed build	reading the error block and the log
Standing where the build stood	standing in the build’s own environment
Build your own, without asking anyone	installing with no admin rights
Your first week on somebody’s stack	three tasks of the kind handed to a newcomer

Use level C when something is failing. Reading a failed build is intended for that situation.

Level D. Build the machinery¶

Three hours. Needs B and C. Read How a build executes for the eighteen steps, and which parameter belongs to which. Read What a build is allowed to see for what a build is allowed to see. Read Build dependencies are not dependencies for the three dependency kinds. Read What a toolchain injects for toolchainopts and optarch. Read Patches, and what a patch is relative to for strip levels, and applying cleanly against applying correctly. Read What a module exports for what a user actually meets.

Level E. Write a recipe¶

Three hours. Needs D.

Read	For
Writing one from nothing	an easyconfig for software that has none
One easyconfig, many installs	`exts_list` and bundles
Languages that bring their own package manager	Python, R, Rust, and the ecosystem with no easyblock
Extensions, and what an entry in exts_list inherits	what an exts_list entry inherits, and what it does not
Writing an easyblock	when a parameter is not enough
Testing, and the four things it can mean	the four things called testing

Testing, and the four things it can mean names the fourth kind and stops. The test is that kind.

Level F. Distribute a stack¶

Two hours. It needs A; the remainder is independent of B to E, which explains why it is placed last rather than hard.

Read	For
EESSI, somebody else’s stack	using a stack nobody at your site built
Reading a stack off the wire: CernVM-FS	how a stack reaches a machine, verified
The same stack somewhere else	four machines, three routes
An easystack is the list the bot will build	the YAML list the bot builds
The bot is three processes and a comment	comment, artefact, ingest
A site stack next to EESSI, not inside it	a site stack next to EESSI
A hook changes a file you are not reading	why a site’s builds differ from a reading of the file

The test¶

The official tutorial, the CSCS webinar, ExCALIBUR-tests and the EESSI suite each follow the same sequence: a test class, the pipeline, the configuration file, a performance number, and the portable suite. Two levels, same grain as the recipe.

Level G. Write a ReFrame test¶

Duration: two hours. Requires Testing, and the four things it can mean; What “installed” means accelerates the sanity comparison.

Read	For
A ReFrame test is a class	a test is a decorated class, and the class decides it passed
The pipeline has six stages	setup, compile, run, sanity, performance, cleanup
The configuration file is the machine	systems, partitions, environments
A performance function is a number with a unit	a figure of merit, a reference, a threshold
Compile or run-only	when the test builds, when it loads a module

Finally, a run-only test can be read aloud, detailing its execution, pass criteria, and the file that defines the permissible machine.

Level H. Run a portable suite¶

Two hours. Needs G.

Read	For
Parameters multiply the suite	It compares `parameter` against `variable` and explores the cartesian product.
A portable test leaves the machine in the config	It explains why `valid_systems = ['snellius']` is the trap.
Software maps to tests	It describes the mapping file, the CSCS layout, and the three uses.
Reading a failed ReFrame run	It covers the stage directory, `rfm_job.out`, and `--restore-session`.

Whenever¶

Not a level.

Read these when the question comes up.

Read eb-stack ports a recipe and bumps one when port a conda-forge or Spack recipe, or bump a generation.

Read Inspect writes a work queue, not a recipe when inspecting artifacts and the residual queue.

Read Format, lint, and check are three different questions when formatting, linting, and checking.

Read A stack lock is not a package lock when performing whole‑stack lock, build list, and diff.

Read A campaign finding is a typed failure, not a log when reviewing typed campaign findings.

Read A wrapper is the range EasyBuild will not write when handling ModuleRC, wrapping, and -Dr.

Read Four EasyBuild 5 surfaces the earlier chapters skipped when installing locks, bwrap, and datasets.

Read Four things that actually happened when examining the failures in full, with the diagnosis.

Read the glossary when a word in this book means something specific.

Read the keypoints when a page was read last week.

Read the exercises when a session is being run, or a self‑check is needed.

Read references when consulting the papers the chapters cite.

Read the afterword when deciding whether to use EasyBuild at all.