Opp Repl Overlay Builds

Overlay builds

Overlay builds use fuse-overlayfs to create a writable layer over a read-only source tree. Builds happen in the overlay; the original source stays pristine — useful for building read-only checkouts, parallel multi-mode builds, and sandboxed runs.

(Note: compare_simulations_between_commits() uses git worktrees, not overlays — see opp-repl-comparing-simulations.)

Upstream reference: https://github.com/omnetpp/opp_repl/blob/main/doc/overlay_builds.md

Requirements

• fuse-overlayfs installed and user-mountable.

• On Linux; macOS has no fuse-overlayfs.

  sudo apt install fuse-overlayfs # Debian/Ubuntu sudo dnf install fuse-overlayfs # Fedora

Enabling an overlay

Set overlay_name in the .opp file; builds happen in a layer named by that string:

SimulationProject(
    name="inet+omnetpp",
    root_folder=".",
    omnetpp_project="omnetpp",
    overlay_name="inet+omnetpp",     # key line
    library_folder="src",
    bin_folder="bin",
    build_types=["dynamic library"],
    dynamic_libraries=["INET"],
    ...
)

The overlay build root defaults to ~/.omnetpp/build; override globally with the OPP_BUILD_ROOT environment variable, or per-project with overlay_build_root= in the .opp (relative paths resolved against the .opp file's directory).

Management API

from opp_repl.simulation.overlay import *

list_overlays()          # names of overlay layers under the root
cleanup_overlays()       # unmount all overlays
clear_build_root()       # unmount + wipe all overlay data

CLI commands and sandbox pre-mounting

opp_mount / opp_unmount mount and unmount overlays from the shell (the Python API above does the same in-process):

opp_mount   "~/workspace/opp/*.opp"   # mount overlays for matching projects
opp_unmount                           # unmount all (or pass a glob)

Mount overlays before entering opp_sandbox — the sandbox restricts fuse-overlayfs, so it cannot create them itself:

opp_mount "~/workspace/opp/*.opp"
opp_sandbox -w ~/workspace -- opp_repl --load "opp/*.opp"
opp_unmount

See opp-repl-sandbox for the isolation details.

When to use overlays

• Testing a patch series without a git worktree.
• Building the same sources in multiple modes (release, debug, sanitize) without Makefile collisions.
• Feeding a read-only CI cache of sources to many parallel builds.
• Giving a sandboxed run a writable build layer (pre-mount first).

Pitfalls

• Stale mounts accumulate after crashes. cleanup_overlays() and clear_build_root() are your friends; run them in CI cleanup.
• macOS cannot use overlays. Use git worktrees there instead.
• Permission issues: the user running opp_repl must be in fuse group, or user_allow_other must be set in /etc/fuse.conf.
• Overlays are per-path; two different .opp files with the same overlay_name but different root_folder values will conflict.

See also

• opp-repl-opp-files — where overlay_name gets set.
• opp-repl-comparing-simulations — uses git worktrees (not overlays).
• opp-repl-sandbox — pre-mount overlays before bubblewrap isolation.
• opp-repl-opp-env-integration — alternative installation method.