Reference

Reference

Command namespaces

Airfield uses namespaced commands:

• airfield package ... for package operations
• airfield project ... for project operations
• airfield system ... for system setup and maintenance
• airfield tools ... for maintenance tasks
• airfield status for context and runtime status
• airfield doctor for system dependency checks

Unique prefixes are accepted when they identify one registered command at that level. Unknown top-level command fallback is not accepted, so package and project commands still need a namespace or a unique namespace prefix. When Airfield detects the current directory is inside an Airfield project or package, it prints the detected context, but it does not route unknown top-level commands into that context.

Dependency manifests

Dependency manifests are architecture-specific YAML files:

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

Inside a project, Airfield resolves dependency manifests from the project root’s dependencies/<target-device>/ folder when it contains YAML files. Standalone packages use the package root’s dependencies/<target-device>/ folder. If no local manifests exist for the target device, Airfield falls back to the shared packages repository.

Each dependency may define:

• system root-level install commands
• user user-level install commands
• ros_versions compatible ROS distributions
• host_dependencies host-level requirements checked before container build

Semantic version constraints in airfield.yaml are preserved. Exact pins such as name==1.2.3 are treated as lock values during build-time dependency installation.

Upstreaming dependency manifests

Use these commands to prepare local package dependency manifests for the shared Airfield packages repository:

airfield package dependencies check . --target-device x86_64
airfield package dependencies upstream . --target-device x86_64

Both commands accept an optional package or project directory argument. If omitted, Airfield starts from the current directory. It checks package-local manifests first, then project-local manifests.

Container Build Cache

Airfield explicitly enables DOCKER_BUILDKIT=1 and applies heavy caching to container builds:

• Persistent Caches: Uses --mount=type=cache for apt lists (/var/lib/apt), Debian packages (/var/cache/apt), and Python wheels (~/.cache/pip).
• Context Exclusion: .dockerignore configurations ensure that .git/, __pycache__/, IDE files, and large data files (*.h5, *.pt) are excluded from the upload context.
• Cache Management: Because caches are persistent, you may occasionally want to reclaim disk space or force a fully clean build using standard Docker Buildx commands:

# View build cache usage
docker buildx du

# Prune unused cache
docker buildx prune

Local runtime config

Local-only runtime options belong in .air, which should be gitignored:

mounts:
  - /robodata/speedway

Both project-level and package-level .air files are supported. Package mounts are appended after project mounts.

System checks

airfield doctor reports required system dependencies and accelerator diagnostics:

• Docker or compatible container backend availability
• shell completion configuration
• detected NVIDIA GPU hardware
• CUDA toolkit version

Use --fix to auto-apply supported fixes:

airfield doctor --fix

Cleanup

Remove Airfield config from a package or project:

airfield package deinit
airfield project deinit

Remove all containers created from Airfield package images:

airfield tools system clean