From one easystack line to a build set

eb-stack pr-overlap lists the modules a pull request would build, starting from the easystack lines it adds. This page explains that walk, and how the tool picks a merge order from those lists. Each added line names one easyconfig. The tool follows the dependencies of that easyconfig, then theirs, and stops at each installed module. That follow-up is the dependency walk. The closure is every module the dependency walk reaches. Every reached module that is not installed goes into the pull request’s build set (to_build in the record). When two build sets share a module, building both pull requests builds that module twice. The second install replaces the first. Different hooks or settings in the second build leave a binary the first pull request never tested. The command writes overlap.md for maintainers, one prs/<N>.toml record per pull request, overlap.toml, and, with --merge-order, merge-order.toml.

Run it before merging two or more European Environment for Scientific Software Installations (EESSI) software-layer pull requests (PRs) that edit the same EESSI version and easystack. A scheduled CI job can run the same check and publish overlap.md. The commands and the CI wiring are in find shared builds across open pull requests. Record fields are in output formats.

One shared module

tests/pr_overlap_fixtures/ has three pull requests. Pull requests 11 and 13 both add freetype-2.14.1-GCCcore-15.2.0.eb. Pull request 12 adds Graphviz-14.0.2-GCCcore-15.2.0.eb, and Graphviz depends on freetype. The installed list is GCCcore/15.2.0, zlib/1.3.1-GCCcore-15.2.0, and CMake/4.1.2-GCCcore-15.2.0.

eb-stack pr-overlap \
  --pr tests/pr_overlap_fixtures/prs.json \
  --easyconfigs tests/pr_overlap_fixtures/release \
  --installed tests/pr_overlap_fixtures/installed.txt \
  --installed-label x86_64/amd/zen4 \
  --generated-at 2026-10-22T00:00:00Z \
  --merge-order \
  --out-dir /tmp/pr-overlap-explain

The command prints one line:

prs=3 records=3 shared_modules=2 skipped_easyconfigs=0 out=/tmp/pr-overlap-explain

prs is the number of distinct pull requests read. records is the number that add at least one entry to an easystack selected for this stack version and architecture. shared_modules is the number of not-yet-installed module names present in more than one record’s to_build list. skipped_easyconfigs is the number of recipe files skipped while loading the easyconfig trees because the parser could not parse them. out is the directory containing overlap.md, overlap.toml, the per-PR records, and merge-order.toml.

/tmp/pr-overlap-explain/overlap.md names the two shared modules: freetype/2.14.1-GCCcore-15.2.0 and libpng/1.6.50-GCCcore-15.2.0, each on pull requests 11, 12, and 13. Merge pull request 11 first. After that, pull request 13 has nothing left to build, and pull request 12 builds only Graphviz. How merge order changes later builds is why 11 is first.

From one line to a build set

The base easystack already contains zlib. Pull request 11 adds freetype:

 easyconfigs:
   - zlib-1.3.1-GCCcore-15.2.0.eb
+  - freetype-2.14.1-GCCcore-15.2.0.eb

Lines already on the base are not new work. The tool resolves each added filename on --easyconfigs, then follows dependencies. A module name has the form name/version[-toolchain]versionsuffix. The toolchain part is absent for a recipe built with the system toolchain. freetype-2.14.1-GCCcore-15.2.0.eb asks for freetype/2.14.1-GCCcore-15.2.0.

The diagram below summarizes pull request 12’s dependency walk. It is explanatory, not text printed by the command:

Graphviz/14.0.2-GCCcore-15.2.0                 to build (PR 12)
├── freetype/2.14.1-GCCcore-15.2.0             to build (PRs 11, 12, 13)
│   ├── libpng/1.6.50-GCCcore-15.2.0           to build
│   │   ├── zlib/1.3.1-GCCcore-15.2.0          installed, stop
│   │   └── CMake/4.1.2-GCCcore-15.2.0         installed, stop
│   └── zlib/1.3.1-GCCcore-15.2.0              installed, stop
└── libpng/1.6.50-GCCcore-15.2.0               same module
toolchain GCCcore/15.2.0                       installed, stop

to_build for pull request 12 is Graphviz, freetype, and libpng. already_installed is CMake, GCCcore, and zlib. Pull requests 11 and 13 start at freetype, so they build freetype and libpng.

When the dependency walk reaches an installed module, it records that module and stops following its dependencies. Copy the installed list, add freetype/2.14.1-GCCcore-15.2.0, and pass that file as --installed. The summary then has shared_modules=0. Pull requests 11 and 13 have an empty build set. Pull request 12 still builds Graphviz and libpng, because it names libpng itself, and lists freetype as installed.

Where the dependency walk stops

--filter-deps drops dependency tuples before the walk starts. EasyBuild’s --filter-deps does the same. A name drops every version and every module reached only through it. Omit the flag and the command reads EASYBUILD_FILTER_DEPS when that variable is set. On this fixture, --filter-deps libpng drops libpng from the build set of pull request 12. Graphviz and freetype stay, and shared_modules is 1. CMake leaves already_installed, because the dependency walk reached it only through libpng.

An alias counts as the installed module

Pass --installed-modulerc with an Lmod .modulerc.lua file, or with a modules/all tree. module_version("Java/21.0.8", "21") adds Java/21 to the installed set when Java/21.0.8 is already on the list, and a dependency on Java/21 stops there. Without the modulerc, Java/21 stays in the build set.

A missing easyblock is unresolved

A recipe that sets no easyblock takes the class EasyBuild derives from its name, so eOn becomes EB_eOn. Pass --easyblocks with the installed easybuild/easyblocks package. A missing class is recorded as easyblock EB_eOn missing in unresolved. That module is left out of the build set. Its dependencies stay. overlap.md prints - unresolved: easyblock EB_eOn missing.

include-easyblocks-from-commit names a commit. Pass those files as --easyblocks-commit COMMIT=DIR. When the class is in that tree, the module stays in the build set and the record notes where it came from. A commit you did not pass stays unresolved, with a note that it was not provided. Treat an unresolved easyblock as an incomplete result. Supply the installed easyblocks package with --easyblocks, or the requested commit files with --easyblocks-commit, and rerun the command before choosing a merge order.

How merge order changes later builds

--merge-order writes merge-order.toml and appends a table to overlap.md. The proposed order takes every module of an earlier step as installed before the next step starts. On that basis, shared modules are assigned only to their first step:

  1. A pull request that adds a module to the easystack by name goes before any pull request that only reaches that module as a dependency. Two pull requests that both add it by name have no order between them. A depends-on row works the same way.

  2. Of the pull requests that nothing else has to precede, take the one with the fewest modules left to build. On a tie, take the lowest number.

  3. Count the modules of that pull request as installed. Recount the modules left for each remaining pull request. saves records what each one lost.

  4. If pull requests must each go before the other, the report lists that cycle under cycles. The tool then ignores requirements within the cycle and applies rule 2. Review the cycle before merging, because no ordering can satisfy all of its internal requirements.

On the fixture, pull requests 11 and 13 both ask for freetype. Neither has to precede the other. Each must precede pull request 12, because 12 only reaches freetype. Both have 2 modules left to build, so the lower number wins. The first step in /tmp/pr-overlap-explain/merge-order.toml is:

[[steps]]
position = 1
pr = 11
after = []
builds = ["freetype/2.14.1-GCCcore-15.2.0", "libpng/1.6.50-GCCcore-15.2.0"]
reason = "smallest residual build set (2)"

The word “residual” in reason is the modules left to build. That step records freetype and libpng in saves for pull requests 12 and 13. Position 2 is pull request 13, which has no modules left to build. Position 3 is pull request 12, which still builds Graphviz, and its after lists 11 and 13.

--merged numbers are not steps. Their build sets count as installed before rule 2. --impact N treats only N’s build set as newly installed. --impact 11 shrinks pull requests 12 and 13 by freetype and libpng, and the freetype row resolves for 12 only, because 13 asks for freetype itself. A number outside the input exits 2 and names it: --merged 999: no pull request with that number.

An easyconfigs pull request has no easystack entries, so rule 1 reads its depends-on rows instead. Each row runs from pull request A to pull request B and has one of two causes. In the first, A adds a module. B’s closure needs that module, and B does not add it. In the second, A edits or deletes an easyconfig, and B builds a dependent of that module without changing it. B builds a dependent when the module is in B’s closure, or when B’s to_build lists one of A’s reverse dependents. The edited easyconfig joins A’s to_build because A edits it. The rebuild classes apply to A’s reverse dependents. A bundle whose exts_list names that package is must-rebuild, and it joins A’s to_build even when the bundle is already installed. A runtime dependent is no-rebuild, and a dependent reached only through builddependencies is review. Both are listed under reverse dependents with depth and class, and neither is scheduled. A toolchain edge is not listed. --impact A lists the edited module under resolves for B.

merge-order.toml and the last table in overlap.md also list easystack edits that will collide in git. same-entry means two pull requests add the identical line. same-insertion means they add lines at the same place in the same easystack. Open those PR diffs before merging: identical entries are likely duplicates, while additions at the same location may cause a textual merge conflict. Here pull requests 11 and 13 are same-entry, and all three are same-insertion. The place is found by a line diff of base and head. revisions in each record keeps the text that check was computed from.

Every entry of a changed easystack

The sections above walk the lines a pull request adds. The EESSI bot builds a larger set. The bot for one architecture reads each changed easystack at the pull request head. The bot then builds every entry in that file not yet installed there, plus the missing dependencies of those entries. An entry an earlier pull request added stays in the file. If one architecture never installed it, every later pull request that touches the file builds it again on that architecture.

Software-layer pull request 1775 added lines to eessi-2026.06-eb-5.4.0-2026.1.yml. GDRCopy was already in that file, and the riscv64 bot failed on it. The added-lines walk does not reach GDRCopy, because 1775 did not add it. x8664had GDRCopy installed, so the whole-file walk on x8664does not build it either.

--arch-installed runs the whole-file walk once per architecture and gives each architecture its own build set, merge order, and impact. entries in the record stays the lines the pull request added. A head entry that was already in the file and is still not installed is listed as carried. The command and its output are in find shared builds across open pull requests.

What to do with the report

  1. Open overlap.md and investigate every unresolved item and any nonzero skipped_easyconfigs count. Either can make a build set incomplete.

  2. Process the first unmerged step in merge-order.toml through the normal EESSI merge, build, and publication workflow.

  3. Refresh the installed-module list and rerun pr-overlap before acting on the next step.

The report is a prediction from recipe metadata and the supplied installed-module list. It is not evidence that a recipe resolves in EasyBuild, builds successfully, or produces a verified binary.