Command line

mobiledsl compile FILE... [--library DIR]... [--check] [--target NAME] [--output DIR]
                  [--warnings-as-errors] [--json] [--color auto|always|never]
mobiledsl --version

A program is given as files: one .core, one .world, one .task, and optionally one .eval, in any order. The extension says which form a file is. There is no project file: the libraries, the target, and the output directory are settings of the compile, not of the program.

Option	Meaning
--library DIR, -l DIR	A component library; repeat for several. A part must be in exactly one of them.
--check	Stop after validation and emit nothing.
--target NAME, -t NAME	The target to emit: ros-gz-nav2, ros-mujoco-nav2 or mjcf. Needs --output.
--output DIR, -o DIR	The directory the target writes. It is created if missing; a file of the same name is replaced, never written through a link, and other files are left alone. It must not be, hold, or sit inside a source file or a library, and no directory in it may be a symbolic link.
--warnings-as-errors	A warning blocks compilation from where it is found, so nothing is written; each affected diagnostic says so in a note.
--json	Write the structured result to stdout.
--color	auto colors when stderr is a terminal and neither NO_COLOR nor TERM=dumb is set; always and never override.

Output

Diagnostics and one summary line go to stderr, in the form specified in Diagnostics. A clean check ends with Checked demo.core demo.world demo.task (14 checks), counting the validation rules that applied; a check that left a rule undecided says (14 checks, 1 undecided), and one that failed an advisory rule (14 checks, 1 advised against); a compile ends with Compiled demo.core demo.world demo.task (14 checks) into build (40 files); a failure ends with error: 1 error; ... did not compile.

error[name.unknown_component_type]: unknown component type 'Lidra'
   --> demo.core:22:5
   |
22 |     Lidra top_lidar(ref = "lidar_ld06", glue = (0, 0.0001, 0.0344, 0, 0, -1))
   |     ^^^^^ not a component type
   |
   = help: did you mean 'Lidar'?

error: 1 error; demo.core demo.world demo.task did not compile

With --json, stdout holds one document:

{
  "schema": "robotdsl.compile",
  "ok": true,
  "sources": ["demo.core", "demo.world", "demo.task"],
  "phases": {"source_load": "pass", "library_load": "pass", "parse": "pass", "...": "..."},
  "diagnostics": [],
  "validation": [{"rule": "assembly.glue_on_connector", "status": "pass", "evidence": ["..."]}],
  "parts": [
    {"component": "chassis", "type": "Mecanum_four_wheel", "category": "chassis",
     "library": "demo_parts", "part": "tslot_1515_drone",
     "visual": {"xyz": [0.0, -0.0002, 0.0219], "rpy": [0.0, 0.0, -1.5708]}, "links": []},
    "..."
  ],
  "facts": {
    "placements": [{"component": "pack", "parent": "chassis", "connector": "deck_rear",
                    "xyz": [-0.1, 0.0, 0.0344], "rpy": [0.0, 0.0, 0.0], "...": "..."}, "..."],
    "ground_z": -0.069,
    "...": "..."
  }
}

When a target was written, the document also has output (the directory and the files written, compile.json included) and approximations (what the target stood in for, see the output contract).

phases names every compiler phase with pass, invalid, environment_failed, not_run (an earlier phase failed) or not_requested (--check stopped before it). diagnostics is the same list the terminal shows, in the JSON form. validation has one entry per rule with its status and evidence, including rules that were not_applicable; an advisory rule's entry says "advisory": true, and its fail is a warning.

parts and facts are there once the program is put together, also when a rule refuses it, so that a tool draws the robot as the compiler assembled it. parts names each component's part: its library and id, its category, where its visual is drawn in the part's frame, and for a part with links of its own, where each link's frame stands in the part's frame with every servo at its hold, and where the link's visual is drawn. facts is what the analysis derived, in the chassis frame and in metres, kilograms and radians: where each component is placed and which could not be placed, the wheels, the tracks, a legged robot's feet and the parts' declared ground contacts, the height of the ground the robot stands on (ground_z, where the targets stand it), the motors, batteries and drivers and what feeds them, the walker it walks by, the mass, the footprint, the drive, the sensors and the world's locations. compile.json holds the same two.

Exit status

Status	Meaning
0	Nothing blocked. Warnings may have been printed.
1	A diagnostic blocked: a problem in the program or a library, a missing file, an unknown target, or a warning under --warnings-as-errors.
2	The command line itself was wrong.

What a clean check does not establish

A clean check means the program names existing parts, every argument is well typed, every reference resolves, the assembly mates onto real connectors, and no standard rule fails on the facts the library states; a rule those facts do not settle stays undecided, a warning. It does not establish that the robot spawns, drives, or completes the task: those are observed when the emitted target runs, and the target reports them.