Tutorial: read an easyconfig the way EasyBuild does

name, version, toolchain, sources on one rail

The tutorial reads four fields. Templates and the easyblock come after the file runs.

file text through the namespace to the model

The file is evaluated. The model is what remains.

This tutorial evaluates a file the way EasyBuild does. Templates are formatted after the file runs. The easyblock is the Python class that builds the software. The toolchain is the compiler stack the file names. A later page, The robot, is how EasyBuild finds a filename. Each sample on this page is editable and runs in the browser. Recordings later in the book are labelled as recordings and are not typed. The expected output is under the sample. Twenty minutes. Nothing to install. Nothing to put back. Who this is for. You can read code. You have met an easyconfig, or you are about to. You do not need EasyBuild, a cluster, an account, or Python. You will not need them here.

Questions

  • Why does SYSTEM have no quotes?

  • What does %(version)s become, and when?

  • How does EasyBuild pick an easyblock when the file never names one?

What you will be able to do

  1. Say what an easyconfig means, as against what it says.

  2. Predict which file EasyBuild will download from a version number.

  3. Name the easyblock EasyBuild will look for, for any software name.

  4. Say which dependencies a toolchain lets a package see.

Before you start

Each sample on this page is a listing. In a browser with JavaScript it is also editable on the page. A print or EPUB copy is the listing only.

Step 1: what the file says, and what it means

A real easyconfig is provided. The easyconfig installs a browser‑based VS Code on a supercomputer. The easyconfig should be read first. The answer underneath it should be read next.

name = 'code-server'
version = '4.130.0'

homepage = 'https://github.com/coder/code-server'
description = """Run VS Code on any machine anywhere and access it in the browser."""

toolchain = SYSTEM

source_urls = ['https://github.com/coder/code-server/releases/download/v%(version)s/']
sources = ['code-server-%(version)s-linux-%(mapped_arch)s.tar.gz']

moduleclass = 'tools'

The evaluated model includes three items missing from the file above. toolchain reads ({name: system, version: system}) rather than the word SYSTEM. EasyBuild places that name in scope before evaluating the file, using the constant {'name': 'system', 'version': 'system'}. %(mapped_arch)s is the architecture EasyBuild maps the host to (x86_64 or aarch64) after the file has run, and is absent from the file’s namespace while the file evaluates. moduleclass is a plain string with no template in it. source_urls is a list of URL prefixes. After the file runs, EasyBuild formats %(version)s in sources to 4.130.0. The file itself stored the literal value. File order is irrelevant; sources may appear before version. The final line reports an easyblock that the file never mentions.

Step 2: change the version, and watch what follows

In the sample above, change version from 4.130.0 to 4.131.0. The formatted source name follows. The software name does not. 4.130.0 becomes 4.131.0. code-server stays code-server. EB_code_minus_server stays EB_code_minus_server.

Step 3: break it on purpose

Delete the version line. Expected output. The model names the missing field and stops. It does not guess. It does not carry on with a blank. Now put version back and delete the sources line instead. Expected output. The model comes back without sources, and no complaint. A missing version stops everything. A missing sources is a file that downloads nothing, which is a legal easyconfig and a useless one. One more. Add this line at the bottom:

checksums = [

Expected output. checksums show as not modelled. The page’s reader handles only single-line assignments. The list shows omitted items rather than fabricated ones. A multi-line construct needs the actual parser. The parser runs in Python. The complete engine is a full program. The engine is not the short snippet displayed here.

Step 4: which easyblock will EasyBuild look for

An easyconfig without an easyblock relies on a software-specific one existing. EasyBuild derives the name by converting the software’s name one character at a time.

code-server
c++
Xerces-C++
Python-bundle-PyPI
GROMACS

Expected output. punctuation spelled out as words: the hyphen in code-server becomes minus, and c++ becomes EB_c_plus__plus_. Look at the doubled separator in the middle. The substitution runs per character and collapses nothing, and that is what keeps it reversible. A name with a _ in it, say my_tool, is the next case. Expected output. _underscore_ . That character is encoded too, and it has to be. Left alone, _minus_ could mean either an encoded hyphen or a name that really contained the letters minus. Two things follow. Given a name, you know which file EasyBuild will try to import. And given a class name in a traceback, you can read it backwards to the software.

Step 5: what a toolchain lets you see

foss-2025a is a toolchain: GCC, OpenMPI, OpenBLAS, FFTW, ScaLAPACK. A dependency is a candidate only when it was built with one of those members, or with system. Determine the contents of a hierarchy.

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

GCCcore is the compiler-only member at the bottom of that hierarchy. Start at system. The last name is foss-2025a. A package on foss-2025a may depend on any component built with any member of that list. A package on GCCcore cannot depend on a foss build: foss is above GCCcore, so a foss module is not a candidate from there. The robot then reports that it cannot locate something visible on disk. Change 2025a to 2024a, then to 1999z. Ask for a chain the page does not know. An unknown chain is refused. A hierarchy reflects what is installed rather than the string.

What to remember

  • The file is Python. EasyBuild evaluates it in a prepared namespace.

  • A missing version stops the parse. A missing sources line is legal and useless.

  • A missing easyblock line is still an easyblock: the name is transformed.

  • A toolchain is the top of a hierarchy. That hierarchy is the set of legal dependencies.

Where to go next