Project descriptor files (.opp)

A .opp file is a tiny Python expression containing exactly ONE constructor call — either OmnetppProject(...) or SimulationProject(...) — with keyword-only literal arguments (strings, numbers, booleans, lists, dicts, None). No variables, no function calls, no imports.

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

Path resolution rules

• root_folder, overlay_build_root, opp_env_workspace:

relative paths resolve against the directory containing the `.opp` file, not the shell's CWD. root_folder="." therefore always means "this folder". Absolute paths pass through.

• All other folder parameters (bin_folder, ned_folders,

ini_file_folders, ...) are relative to the project root, not to the .opp file.

Ways to locate the project root

Tried in order:

1. root_folder="/abs/path" or root_folder="." (most common).
2. root_folder_environment_variable="MY_PROJECT" -- reads the env

var at load time.

1. SimulationProject also accepts

root_folder_environment_variable_relative_folder="samples/aloha" which gets appended to the env var's value. Handy for pointing at OMNeT++ samples via __omnetpp_root_dir without writing a .opp per sample.

OmnetppProject parameters

SimulationProject parameters (the important ones)

Full parameter list: see linked files under templates/.

Loading

• CLI: opp_repl --load "path/to/file.opp" (globs allowed,

flag repeatable).

• REPL: load_opp_file("~/workspace/inet/inet.opp") or

load_workspace("~/workspace") (recursively scans for *.opp).

• Command-line tools auto-load all *.opp in CWD when no --load

is given.

OmnetppProject files are always processed before SimulationProject files, so simulation projects can refer to them by name.

Ready-made templates (bundled)

Copy and customise from templates/:

Programmatic alternative

When the path is only known at runtime (git worktrees, generated installs), skip the .opp file:

define_omnetpp_project("omnetpp-6.1", root_folder="/tmp/omnetpp-v6.1") define_simulation_project("inet-4.5", root_folder="/tmp/inet-v4.5", omnetpp_project="omnetpp", library_folder="src", bin_folder="bin", dynamic_libraries=["INET"], ned_folders=["src", "examples"], ini_file_folders=["examples"])

Pitfalls

• Syntax is restricted — variables / imports / function calls raise

at load time. Treat .opp files as JSON-in-Python.

• A missing omnetpp_project= on a SimulationProject is fine as

long as an OmnetppProject is auto-detected from __omnetpp_root_dir.

• When two versions of the same project are registered, lookup by

name alone is ambiguous: use get_simulation_project("inet", version="4.5").

• For executable projects, ALWAYS set `executables=["<name>"]`

matching the target name produced by opp_makemake -o <name>. If they disagree, run_simulations() fails with exit code 127 because opp_repl looks for a binary that doesn't exist. See opp-repl-project-scaffolding for the end-to-end setup.

• A `.opp` file alone is not enough to build. You also need

.oppbuildspec, .nedfolders, and a Makefile (the first two are committed; the third is generated by generate_makefile(), which build_project() calls automatically on current opp_repl — older versions used make_makefiles()). Missing any of these produces cryptic build failures.

See also

• opp-repl-concepts — the object model these files feed.
• opp-repl-project-scaffolding — full new-project template set

(.opp, .oppbuildspec, .nedfolders, NED/C++ skeletons).

• opp-repl-overlay-builds — overlay_name details.
• opp-repl-opp-env-integration — opp_env routing.
• opp-repl-running-simulations — what happens once projects load.