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.
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:
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-onrow works the same way.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.
Count the modules of that pull request as installed. Recount the modules left for each remaining pull request.
savesrecords what each one lost.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¶
Open
overlap.mdand investigate everyunresolveditem and any nonzeroskipped_easyconfigscount. Either can make a build set incomplete.Process the first unmerged step in
merge-order.tomlthrough the normal EESSI merge, build, and publication workflow.Refresh the installed-module list and rerun
pr-overlapbefore 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.