Developer onboarding

Mental model

A program describes a robot, world, task, and optional evaluation requirements. The compiler resolves references against explicitly supplied component directories, builds a typed model, derives facts, validates them, and generates target-native files for the user's installed robot environment. Analysis produces facts; validation judges them without changing the model.

Read Architecture for repository ownership and Language design for program meaning.

Local setup

python -m pip install -e '.[dev]'
pytest

The compiler is plain Python and needs no ROS, simulator, or Docker installation. Tests have three tiers:

pytest                    # compiler tests; no robot stack
pytest -m container       # target tools check emitted files
pytest -m simulation      # execute output and inspect simulator ground truth

Default test selection excludes the two target tiers. Those require Docker and the target images: robotdsl/ros-gz-nav2:jazzy-harmonic for the Gazebo target (MOBILEDSL_TEST_IMAGE names another) and robotdsl/ros-mujoco-nav2:jazzy for the MuJoCo target (MOBILEDSL_TEST_IMAGE_MUJOCO); see docker/README.md for how the images are built. A tier is skipped when its image is missing. Run container checks for target changes and simulation tests for changes affecting execution. Unit tests alone cannot establish that a robot moves correctly.

Compile one program

Supply your program and a local component library:

mobiledsl compile demo.core demo.world demo.task demo.eval --library path/to/parts --check
mobiledsl compile demo.core demo.world demo.task demo.eval --library path/to/parts \
  --target ros-gz-nav2 --output out

The first command validates and reports diagnostics; the second writes one runnable directory whose entry point is out/launch/bringup.launch.py. Libraries are ordinary directories, with no installation or hidden default location. Trace a source expression through its component declaration and emitted files before changing its behavior. Launch the output in your robot environment; compilation does not launch it.

Contribution paths

Paths below are relative to src/mobiledsl/; tests mirror these areas. Import and installation boundary checks live in tests/architecture/ at the repo root.

Change	Location	Check
Syntax	frontend/	Accepted/rejected input and source spans
Types and reference resolution	semantic/model/, semantic/lower.py	Entity resolution, units, AST-independent model
Derived facts	semantic/analysis/	Assembly, the world's places and regions, task use
Validation rule	validation/	Pass, fail, and missing evidence
Library loading	library/	Explicit paths and component references
Simulator, ROS, or navigation binding	targets/gazebo/, targets/mujoco/, targets/ros2/, targets/nav2/	Native tool checks and simulation
Target composition	targets/ros_gz_nav2/, targets/ros_mujoco_nav2/	Interfaces agree across generated files
CLI or compilation workflow	cli.py, driver/	Diagnostics, output boundaries, deterministic files

Concrete parts belong in component libraries. Keep target formats and runtime imports out of earlier compiler phases; preserve source locations in diagnostics. Compiler tests enforce import boundaries and compilation without ROS or simulator packages. Target tests also run emitted output without the compiler installed.

Documentation

This site is built with VitePress from docs/. It needs Node.js 20 or later, and nothing from the compiler:

cd docs
npm ci
npm run docs:dev      # serve with live reload
npm run docs:build    # the site CI builds, into docs/.vitepress/dist

reference/vocabulary.md and reference/validation.md are generated from the code; edit the vocabulary or the rules and run tools/generate-specs. The test suite fails when a generated page is stale.

The site is published inside the project site, at https://mit-cdfg.github.io/robotdsl-site/docs/, whose own page is the home the title leads back to; this repository is private, so it has no Pages of its own. To publish, build and copy the output into a checkout of MIT-CDFG/robotdsl-site, replacing the previous build but keeping the site's own docs/release-qa/ and docs/asset-sources.md, then commit and push:

cd docs
npm run docs:build
rsync -a --delete --exclude release-qa --exclude asset-sources.md \
  .vitepress/dist/ path/to/robotdsl-site/docs/

On a network home directory the build can fail while it removes its .vitepress/.temp directory; copy docs/ to local disk and build there.

Before a pull request

• Write the user problem, evidence, and owning phase before editing, as required by AGENTS.md in the repository root.
• Add an example with expected output or rejection; run the relevant test tiers and report the commands and results. Missing evidence is not a pass.
• Update affected documentation, inspect the diff, and follow Contributing for branch naming and review.