<Module>/
  build              # #!/usr/bin/env modbuild — bash, overrides pbuild::* hooks
  modulefile         # #%Module1.0 — Tcl, runtime env
  files/config.yaml  # format:1 — group/relstage/versions/deps/urls
  README.md          # description + module-specific pitfalls

Modules build on the Ra cluster (RHEL8) into /opt/psi/MX/<name>/<version>. Upstream docs: https://github.com/Pmodules/Pmodules/wiki

Getting the repo

Clone into your work folder on Ra (once). SSH access to Gitea is recommended: generate a key (how-to) and add the public key at https://gitea.psi.ch/user/settings/keys.

cd /das/work/p21/p21515/          # adapt the p-group path to your own
git clone git@gitea.psi.ch:mx/MX_Pmodule.git
cd /das/work/p21/p21515/MX_Pmodule

Work on your own branch, not on main:

git switch main && git pull       # start from up-to-date main
git switch -c build-<module>      # e.g. build-dials
git push -u origin build-<module>

New to git? Start here: https://git-scm.com/doc

Building on Ra - DO NOT write into /var/tmp !

<Module> below is one of the top-level directories of the cloned repo (e.g. /das/work/p21/p21515/MX_Pmodule/ccp4):

!!!WARNING!!!: never write big files to /var/tmp — it is small and shared with everyone on the login node. Please, please do not fill /var/tmp.

Always pass --tmpdir and --distdir pointing to your p-group work folder — the defaults are /var/tmp/$USER (see warning above) and ~/.cache/Pmodules/distfiles (home quota is too small). Adapt the p-group path (p21/p21515) to your own:

module use unstable && module load modbuild/2.1.3
cd /das/work/p21/p21515/MX_Pmodule/<Module>
modbuild build \
    --tmpdir=/das/work/p21/p21515/.cache/Pmodules \
    --distdir=/das/work/p21/p21515/.cache/Pmodules \
    <version>
# verify it loads:
module use MX unstable && module load <Module>/<version>

If you already built without the flags, clean up what landed in the defaults:

rm -rf /var/tmp/$USER/<Module>-<version>
rm -rf ~/.cache/Pmodules/distfiles

There is no build subcommand: usage is modbuild [BUILD_SCRIPT] [options] <version> — build above is the script's filename, so run inside the module dir.
More flags: --prep|--configure|--compile|--install|--all (run up to that step), --clean-install (remove existing module first), -f/--force-rebuild, -j N, -v, --debug (make the otherwise silent long steps visible).
curl: (23) Failure writing output to destination during a download means quota/disk full at the target dir, not a network error.

Tips & tricks

Module names are name/version, never name/name-version.
New versions start relstage: unstable; promote to stable only after the module builds AND loads. A stable module may only depend on stable modules.
Contaminated environment: previously loaded modules can leak env vars into the build and make it fail in odd ways. Fix: module purge && module load modbuild/2.1.3, then build again.
Hooks run with pipefail + nounset: yes | installer dies via SIGPIPE — use printf 'y\ny\n' | installer.
Module-specific pitfalls live in the per-module README — read it before building. ccp4/README.md is the most battle-tested and also documents the common modbuild traps ("done" without success — no errexit in hooks, partial downloads reused silently, slow installs on shared /opt/psi).

Building with an AI agent

The repo ships the new-module skill at .claude/skills/new-module/ (SKILL.md = workflow + decision tree, REFERENCE.md = full schema, hooks and copy-paste templates). It scaffolds the 4 files for a new module from the right install-type archetype and prints the Ra build recipe.

Claude Code: opens the repo → skill is auto-discovered. Type /new-module <tool, version, download URL, special requirements> or simply describe the task ("package X as a module") and it triggers.
Other agents (Cursor, Codex, generic LLM chat): the skill is plain Markdown — point the agent at .claude/skills/new-module/SKILL.md first, then REFERENCE.md, and ask it to follow them.
New software (or a known tool that moved to a new download site): give the agent the software's installation/download page as part of the context — the skill knows the repo's patterns, not vendor-specific install procedures.
The skill can be buggy — use it with caution and double-check what it scaffolds before building; corrections are welcome (edit .claude/skills/new-module/ and commit). Reading along while it works is also a good way to learn how these modules are put together.
The skill copies from real modules in this repo as ground truth (xds, careless, DIALS, ccp4, ...) — keep those exemplary, and fold new lessons back into the skill files so the next build starts smarter.

Pmodules background (from the wiki)

Modules are organized in hierarchical groups; everything here is in the MX group (module use MX).
Filesystem layout: modulefile at $PREFIX/GROUP/modulefiles/NAME/VERSION, installation at $PREFIX/GROUP/NAME/VERSION, per-version config at $PREFIX/GROUP/modulefiles/NAME/.config-VERSION (YAML).
Release stages: unstable, stable, deprecated. New builds land in unstable; opt in with module use unstable.
Pmodules automatically sets $NAME_DIR, $NAME_HOME, $NAME_PREFIX, $NAME_VERSION on load and prepends standard directories ($PREFIX/bin to PATH, ...) if they exist — no explicit setenv/prepend-path needed for those.

Permissions

Members of the unx-mx_adm group can update /opt/psi/MX directly — no -adm account needed. Permission problems: Ask May/Meitian/Dawn to be added to unx-mx_adm group. If you have been in the group for more than 48 hours and still can't write to /opt/psi/MX, ask the SLS beamline storage and compute admins (Email: sls-htc-admins@lists.psi.ch).

Resources

Buildblock examples: https://github.com/Pmodules/buildblocks/tree/master
modbuild documentation: https://pmodules.github.io/modbuild/
Environment Modules: https://envmodules.io/

If you want to provide more, feel free to submit a pull request to this document.

Acknowledgements

Many thanks to Achim Gsell for giving the MX group the tutorial on 2026-08-18, and to Hans Viessmann for the support.

During the tutorial the following people worked on the modules:

May — Phenix
Filipa — Pymol
Emma — CrystFEL
Dennis — ccp4
Milton — Xtrapol8

Thanks to all of them for their participation and contributions to the scripts. As of 2026-08-19, all build* branches have been merged to main.