How a build executes

Each parameter is named after the step it feeds. Cutting the sequence short is a flag, not a rewrite.

A build is a named sequence. Each easyconfig parameter is named after the step it feeds.

Each stage is an easyblock method. The log names the method that failed.

Questions

• In what order do the steps run?

• Which step does a given easyconfig parameter reach?

• What does --stop actually stop, and what does --skip skip?

What you will be able to do

1. Name the steps a build runs through, and say which ones an easyconfig can influence.

2. Say which parameter reaches which step.

3. Stop a build part way, or resume it, on purpose.

The framework outputs the list. Its behavior remains unchanged across releases of the same major version:

The whole sequence, from the framework itself

$ python3 -c 'from easybuild.framework.easyblock import EasyBlock
> for s in EasyBlock.get_steps(): print(s[0])'
fetch
ready
extract
patch
prepare
configure
build
test
install
extensions
postiter
postproc
sanitycheck
cleanup
module
permissions
package
testcases

Recorded: SURF Snellius, 2026-09-10, EasyBuild 5.3.1

Eighteen step names exist. The sixteenth is permissions, then package, then testcases. The steps form a flat list, with no script logic and no dependency graph. The list executes in order for every package. Each parameter belongs to a single step. Most error messages refer to a specific step. Figure 4 in Hoste et al. [2012] presented the same concept as fifteen Roman numerals derived from user test cases. postiter, permissions and package were added in five major version updates. If no easyblock matches a name, get_easyblock_class raises MISSING_EASYBLOCK. No ConfigureMake fallback exists. Short-term memory can retain roughly seven items (Miller [1956]; Wilson et al. [2014]). The eighteen step names are organized into three groups of six rather than a single list.

EB-Steps-parsons-1 — Put the first six in order

These six steps run first. Restore the order. No extras.

extract
fetch
patch
prepare
ready
configure

Solution

fetch, ready, extract, patch, prepare, configure. fetch before extract (nothing to unpack yet). ready before extract (build directory). patch after extract. prepare after the tree exists and before configure. _verify_toolchain is inside prepare, so a toolchain-module mismatch appears here, not under ready.

What each step is for

Getting the source in place.

fetch downloads and verifies. fetch verifies the subject of A checksum is a claim about bytes. ready is readiness and the build directory. extract unpacks. patch applies patches. prepare loads the toolchain and the dependency modules. _verify_toolchain runs in prepare. _verify_toolchain does not run in ready. By the end of prepare, nothing has been compiled. By the end of prepare, everything has been decided. Many failures land in the first twenty seconds of a build that was going to take four hours.

Building.

The steps are configure, build, test, install. These four steps correspond to manual commands. An easyconfig most often has something to say about these four steps.

Deciding it worked, and publishing it.

extensions installs the exts_list entries from One easyconfig, many installs. postproc runs postinstallcmds. sanitycheck is What “installed” means. cleanup removes the build directory. module writes the modulefile. permissions fixes mode bits so other people can read installed files. package and testcases are optional. Most sites never use package and testcases. postiter is the odd one out. Some easyblocks run the build steps more than once. This creates an iterated build. postiter marks the boundary between iterations.

The parameters are named after their steps

The sequence is known. The parameter names are no longer arbitrary.

name = 'example'
version = '1.0'
toolchain = {'name': 'foss', 'version': '2025a'}

preconfigopts = 'unset LIBS && '
configopts = '--enable-mpi --with-hdf5=$EBROOTHDF5'
prebuildopts = 'cp arch/makefile.include.gcc ./makefile.include && '
buildopts = 'all'
preinstallopts = 'DESTDIR= '
installopts = 'PREFIX=%(installdir)s'

Three prefixes exist; each directly describes its function. The pre*opts text is prepended to the command. Most of them terminate with && or a space, attaching the text to the front of a shell command. \*opts is appended as arguments. Each of the four building steps has a corresponding pair. The step referenced in the error is the one whose pre and plain options must be examined. $EBROOTHDF5 in that example is the one to examine. It originates from the HDF5 module loaded during prepare. Pointing a configure script at a dependency via this variable instead of using a hard‑coded path follows the convention. Those variables are provided by the modulefile. A module exports its modulefile.

Where the work happens

Three directories are often confused with each other. The build directory is a scratch space. buildpath from Build your own, without asking anyone contains the package name, version and toolchain. Sources are unpacked there, the compiler runs there, and cleanup deletes it. Nothing worth keeping remains there. The install directory is the destination, %(installdir)s in the sample above, and the only path that survives. TMPDIR is where EasyBuild puts its own working files, including the log. On a cluster it matters more than it looks. A login node’s /tmp is often small and shared. A build that fills it fails in a way that names neither EasyBuild nor your package. Parallelism is max_parallel in the easyconfig, or --parallel on the command line. EasyBuild passes it to the build tool as -j. Some packages cannot build in parallel at all. max_parallel = 1 appears in a recipe, and it should be left alone when it does.

Cutting the sequence short

Four ways exist. They are not interchangeable. The --stop option runs until a specified step and then stops. Running eb foo.eb --stop=configure leaves an unpacked, patched, configured tree. No compiler time is consumed. The fastest method verifies whether the configure line works. No waiting for a full build is required. The --skip-test-step and --skip-sanity-check options each omit a single step. The option names indicate the omitted step. The skipsteps setting in the easyconfig permanently removes a step. The setting applies to all users each time. The article A versionsuffix is part of the name describes a case where sanitycheck was affected. A genuine defect moved from the build machine to the user. The --module-only option skips fetch, extract, patch, prepare’s unpack, configure, build, test and install. It still runs prepare, ready, postiter, sanitycheck and module against an existing installation. The option is useful when a modulefile requires regeneration while the software does not. A bad modulefile then covers a good install.

EB-Steps-1 — Which step, and which parameter

Four failures. For each, name the step and the parameter you would read first.

1. Couldn't find file example-1.0.tar.gz anywhere

2. List of toolchain dependency modules and toolchain definition do not match

3. configure: error: cannot find HDF5

4. Sanity check failed: no file found at 'bin/example'

Then: which of the four could you have found with --stop=configure, and roughly how much compiler time would that have saved?

Solution

1 is fetch. Read sources and source_urls, and remember that sources is templated, so the name that failed may not be the text in the file.

2 is prepare. _verify_toolchain raises “List of toolchain dependency modules and toolchain definition do not match” there, not under ready. No parameter of yours reaches that check.

3 is configure. Read configopts and preconfigopts. The usual cause is a dependency that is not in dependencies, so prepare never loaded it and $EBROOTHDF5 is empty.

4 is sanitycheck. Read sanity_check_paths, and then ask whether the install step actually put the binary where the check is looking, which is usually a files_to_copy or an installopts question rather than a check question.

The first three are all before build, so --stop=configure would have found every one of them, in the time it takes to unpack and run a configure script rather than the time it takes to compile. That is the argument for using it while iterating on a new easyconfig: three of the four most common failures happen before any compiler runs.

What to remember

• The step in the error message rules out every step before it.

• Toolchain mismatch is prepare, via _verify_toolchain, not ready.

• fetch reads templated sources. The name that failed may not be the text in the file.