Tutorial

Create a New Project

Use an Airfield project when you want one workspace to own multiple packages, shared dependency manifests, and runnable plans.

1. Create the project

airfield project init ./my_robot --ros-distro jazzy
cd my_robot

This creates:

my_robot/
  airfield.yaml
  packages/
  dependencies/
    x86_64/
    arm64/
  plans/
    example.yaml
  .dockerignore
  .gitignore

airfield.yaml marks the directory as an Airfield project. The ros_distro value becomes the default for packages created inside the project unless a package overrides it.

2. Check the project

airfield status

The status output should show Project status, the project root, the selected ROS distribution, dependency target folders, and available plans.

3. Add dependency manifests

Project-scoped dependency manifests live under:

dependencies/x86_64/*.yaml
dependencies/arm64/*.yaml

Airfield uses these project manifests first when they exist. If no YAML manifests exist for the target device, it falls back to the shared Airfield packages repository.

Example:

name: tqdm
version: 1.0.0
system: []
user:
  - python3 -m pip install tqdm

4. Add packages

Create a package inside the project:

airfield package init nav_stack

The package is created at:

packages/nav_stack/
  airfield.yaml
  src/
  .dockerignore
  .gitignore

5. Add the package to a plan

Edit plans/example.yaml:

name: example
packages:
  - nav_stack

Generate a tmuxinator file:

airfield package up example --output .airfield/example.tmuxinator.yml

Use --launch when you want Airfield to start tmuxinator immediately.