Skip to main content

Running the Examples

The SDK ships step-by-step examples under share/examples/. Before building any code, you can first use these examples to experience how the PARA runtime works.

Example Layout​

share/examples/
├─ examples-runner.sh            # Example entry point (launcher)
├─ examples/
│  ├─ 01-hello-world.sh          # 01. Hello World
│  ├─ 02-vehicle-mode.sh         # 02. Vehicle mode switching
│  ├─ 03-sensor-pipeline.sh      # 03. Sensor pipeline
│  ├─ 04-remote-vehicle-control.sh  # 04. Remote vehicle control
│  ├─ 05-fault-tolerance.sh      # 05. Fault tolerance
│  ├─ 06-ipc-benchmark.sh        # 06. IPC benchmark
│  ├─ en/                        # English version scripts
│  └─ lib/runner-common.sh       # Shared example helpers
├─ Machine/                      # Complete example Machine (buildable app collection)
├─ para-playground/              # Playground for free experimentation
└─ .tours/                       # VS Code CodeTour guides (01–06)

Each example script uses the helpers in lib/runner-common.sh to guide you through the steps, and works together with para-tui (TUI) to demonstrate things like switching the log (DLT) tab.

Example 01 — Hello World​

The most basic scenario is the flow where the app starts automatically just by launching the EM (Execution Manager) (examples/01-hello-world.sh).

The behavior the script describes is as follows.

  1. When the EM starts, it scans the manifest directory and builds the dependency graph.
  2. The EM automatically transitions MachineFG (Machine Function Group) from Off → Startup.
  3. Processes that depend on (are bound to) MachineFG:Startup are forked automatically.
    • SM — the State Manager
    • HelloWorld — an example app that prints "Hello, World!" every second
  4. HelloWorld outputs messages via the DLT logger (APID HW__).
  5. When you stop the EM, the dependent apps receive SIGTERM and shut down gracefully. HelloWorld's terminationHandler is invoked, the main loop exits, it leaves "Goodbye, World!", and then cleans up with ara::core::Deinitialize().

The key point is that the app starts simply by launching the EM, with no separate state transition command. Which app starts and when is determined by the state-dependencies (e.g., MachineFG:Startup) declared in each app's execution manifest.

Running the Examples​

Examples are run through the launcher (examples-runner.sh) (first source the environment). By default, the launcher creates a tmux session that simultaneously brings up the scenario runner on the left and para-tui (log/DLT view) on the right.

# Set up the SDK environment (configures PARA_SDK, etc.)
cd /path/to/para-sdk
. ./para-env-setup.sh

# List available scenarios
./share/examples/examples-runner.sh --list

# Run a scenario (default: tmux split — para-tui + runner)
./share/examples/examples-runner.sh 01-hello-world

# Run only the runner, without tmux
./share/examples/examples-runner.sh 01-hello-world --no-tui

The example scripts are interactive: at each step they wait for an Enter keypress and guide you to the next action. As you proceed, you can directly observe the logs the app prints (e.g., Hello, World! (0), (1), …) in the DLT log tab of para-tui.

The default split mode requires tmux. You can also run only the runner with --no-tui. The para-tui pane ratio is adjusted via the PARA_TUI_SPLIT environment variable.

Next Steps​

Once you understand how the examples work, build an application yourself → Build with CMake