Tutorial

Create a New Package

Use an Airfield package for one buildable and runnable robotics component. Packages can live inside an Airfield project or stand alone.

1. Create a package inside a project

From an Airfield project root:

airfield package init nav_stack

This creates:

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

The package inherits the project’s ROS distribution unless you pass --ros-distro.

2. Create a standalone package

For a package outside a project:

mkdir nav_stack
cd nav_stack
airfield package init .

Standalone packages resolve dependency manifests from dependencies/<target-device>/ when that folder contains YAML files. Otherwise, Airfield uses the shared packages repository.

When a local manifest should be shared with other packages, check and upstream it with airfield package dependencies check . and airfield package dependencies upstream ..

3. Edit package metadata

Open airfield.yaml:

kind: package
name: nav_stack
dependencies:
  - tqdm
source_path: src
ros_distro: jazzy
run:
  list-packages: ros2 pkg list

Important fields:

name controls the package identifier and Docker image name.
dependencies names dependency manifests such as tqdm.yaml.
source_path is the source folder mounted into the runtime container.
ros_distro selects the ROS base image.
run defines named commands for airfield package run.

4. Build the package

airfield package build nav_stack --target-device x86_64

Inside a standalone package root, use . for the current package:

airfield package build . --target-device x86_64

5. Run package workflows

List configured run commands:

airfield package run nav_stack

Run a configured command:

airfield package run nav_stack list-packages

Open an interactive package container:

airfield package shell nav_stack

Run an ad hoc command in the package container:

airfield package cmd nav_stack -- ros2 pkg list

6. Wrap an existing ROS package

For a ROS package that already has package.xml:

airfield package init --path /path/to/existing_ros_package --ros-distro jazzy

Airfield reads the ROS package name and dependencies from package.xml, writes airfield.yaml, and leaves the ROS source files untouched. Wrapped packages use source_path: . because the package root is the source tree.