Adamant Project Setup

Create standalone Adamant projects outside the framework source tree.

Project Structure

<project_dir>/
├── .gitignore
├── alire.toml                          # Alire crate manifest (Ada dependencies)
├── config/
│   └── project.configuration.yaml      # Adamant sizing & project-specific config
├── docker/
│   ├── docker-compose.yml              # Container definition
│   └── adamant_env.sh                  # start/stop/login helper
├── env/
│   ├── activate                        # Environment setup (sources adamant/env/activate)
│   └── requirements*.txt               # Python deps (auto-installed by adamant/env/activate)
├── src/
│   ├── types/                          # Custom type definitions
│   │   └── .all_path                   # Empty marker file (REQUIRED)
│   ├── components/
│   │   └── <component_name>/
│   │       └── .all_path               # Empty marker in EACH component dir
│   └── assembly/
│       ├── .all_path
│       └── main/
│           └── .all_path
├── clean.do                            # All .do files copied from adamant root
├── default.do
└── default.*.do                        # (elf, gpr, o, svg, pdf, png, eps, uf2)

Setup Steps

1. Copy build scripts

cp $ADAMANT_DIR/*.do <project_dir>/
```ada
Must be copies, not symlinks (redo resolves rules relative to working directory).

### 2. Create env/activate

Template -- replace `PROJECT` with your project's short name (e.g., `DEMO`, `EXAMPLE`):

```bash
#!/bin/bash

# Resolve project directory from this script's location
if test -z "$PROJECT_DIR"
then
  export PROJECT_DIR=`readlink -f "${BASH_SOURCE[0]}" | xargs dirname | xargs dirname`
fi

# Adamant must be a sibling directory
if test -z "$ADAMANT_DIR"
then
  export ADAMANT_DIR=`readlink -f "$PROJECT_DIR/../adamant"`
fi

# Guard: only activate once per shell session
if test -n "$PROJECT_ENVIRONMENT_SET"
then
  return
fi

echo "Setting up Project environment."

# Point to this project's configuration YAML
export ADAMANT_CONFIGURATION_YAML=$PROJECT_DIR/config/project.configuration.yaml

# Activate the Adamant environment WITH this project as an extra build root.
# The argument ($PROJECT_DIR) is CRITICAL -- it adds the project to BUILD_ROOTS
# so the build system can discover custom types, components, and assemblies.
. $ADAMANT_DIR/env/activate $PROJECT_DIR

# Mark environment as set
export PROJECT_ENVIRONMENT_SET="yes"

echo "Done."
```yaml

#### How BUILD_ROOTS Works

`BUILD_ROOTS` is a colon-separated list of directories the build system searches for source files. When you run `. $ADAMANT_DIR/env/activate $PROJECT_DIR`, adamant's activate script:

1. Prepends `$ADAMANT_DIR` to the paths if not already present
2. Iterates each path, running `alr build`, setting up GPR paths, and activating Python configs
3. Exports `BUILD_ROOTS="$ADAMANT_DIR:$PROJECT_DIR"`

The build system uses BUILD_ROOTS to locate `.all_path` markers and discover all source directories. **Without your project in BUILD_ROOTS, custom types/components are invisible.**

You can also set BUILD_ROOTS manually before sourcing activate to override -- the script respects pre-set values.

#### Key Environment Variables Set by activate

| Variable | Purpose |
|---|---|
| `ADAMANT_DIR` | Path to adamant framework |
| `ADAMANT_CONFIGURATION_YAML` | Path to project config YAML |
| `ADAMANT_PYTHON_ENV` | Python venv location (default: `~/.py_env`) |
| `BUILD_ROOTS` | Colon-separated source search paths |
| `GPR_PROJECT_PATH` | GNAT project file search path (set by alire) |
| `SCHEMAPATH` | `$ADAMANT_DIR/gen/schemas` |
| `TEMPLATEPATH` | `$ADAMANT_DIR/gen/templates` |

### 3. Create Configuration YAML

File: `config/project.configuration.yaml`

```yaml
---
# Description (informational only)
description: Configuration for My Project.

#############################################################################
# REQUIRED -- Adamant Core Type Sizing
#############################################################################

# Size of serialization buffer in data product type (bytes).
# Must fit the largest data product in your system.
data_product_buffer_size: 32

# Size of serialization buffer in command type (bytes).
# Must fit the largest command argument payload.
# Use 255 when using Product_Database (its Override command takes Data_Product.T).
command_buffer_size: 255

# Size of serialization buffer in event type (bytes).
# Must fit the largest event parameter payload.
event_buffer_size: 32

# Size of serialization buffer in parameter type (bytes).
parameter_buffer_size: 32

# Size of serialization buffer in fault type (bytes).
fault_buffer_size: 8

# CCSDS space packet buffer size (bytes).
# Default 512 is fine if not using CCSDS. ISS LRT max = 1274.
ccsds_packet_buffer_size: 512

# Packet buffer size (bytes). Typically ccsds_packet_buffer_size minus
# header/checksum overhead (~28 bytes for ISS LRT).
packet_buffer_size: 480

#############################################################################
# REQUIRED -- Other Core Settings
#############################################################################

# Stack margin (bytes). Used by Stack Monitor for "usable" stack calculation.
# Must be > stack used before first Cycle call, and < smallest task stack.
# Only affects bareboard runtimes; Linux uses hardcoded 12KB.
stack_margin: 1000

# Command registration delay (microseconds). Sleep between successive
# command registrations to avoid overflowing Command Router's queue.
# Increase if registrations are dropped at init.
command_registration_delay: 250

#############################################################################
# OPTIONAL -- Project-Specific Variables
#############################################################################
# Define custom key-value pairs usable in YAML (Jinja: {{ var_name }})
# or Ada (with Configuration package).
#
# project_specific_variable: 17
# project_specific_string: "hello"
```ada

**Sizing guidance:**
- `Storage_Error` at runtime → increase the relevant buffer size
- Start with conservative defaults (above), increase as needed
- Buffer sizes affect RAM usage on embedded targets -- don't over-allocate

### 4. Docker Setup

Each project gets its own `docker/` directory. **Do NOT put docker-compose overrides in the adamant repo.**

#### docker-compose.yml Template

```yaml
name: <project_name>
services:
    <project_name>:
        image: ghcr.io/lasp/adamant:0.1
        container_name: <project_name>_container
        volumes:
            - type: bind
              source: ../../adamant          # Relative to docker/ dir
              target: /home/user/adamant
            - type: bind
              source: ../../<project_name>   # Relative to docker/ dir
              target: /home/user/<project_name>
        network_mode: host
        extra_hosts:
            - host.docker.internal:host-gateway
        command: sleep infinity
```ada

**Notes:**
- Volume sources are relative to docker-compose.yml location (inside `docker/`)
- `sleep infinity` keeps container running for `exec` commands
- `network_mode: host` gives container access to host networking
- Container naming convention: `<project_name>_container`
- **Multi-repo projects**: Add extra volume mounts for external dependencies (C/C++ libraries, algorithm repos). Example with 5 repos:
  ```yaml
  volumes:
      - type: bind
        source: ../../adamant
        target: /home/user/adamant
      - type: bind
        source: ../../<project>
        target: /home/user/<project>
      - type: bind
        source: ../../external_algorithms
        target: /home/user/external_algorithms

• Projects with C/C++ dependencies often use a custom Docker image (adamant_env.sh build) that pre-installs toolchains

Container Management

Day-to-day container management should go through admt (primary) or the project's adamant_env.sh helper (fallback / underlying mechanism). admt env init <project_root> registers the project with admt, after which:

The helper script auto-detects project name from its parent directory. Generated project scaffolds still include docker/adamant_env.sh; admt does not replace the file, only its day-to-day usage on the host.

First start runs initialization inside the container, which:

1. Creates Python venv (~/.py_env) and installs requirements
2. Builds alire dependencies (alr build --release)
3. Sets BUILD_ROOTS, GPR paths, etc.
4. Touches ~/.initialized so subsequent starts skip this

The script supports both docker and podman -- falls back to podman if docker is not found.

Interactive Development

Use admt env login for interactive work (or bash docker/adamant_env.sh login as the fallback). The login shell sources the correct activate script via .bashrc, ensuring BUILD_ROOTS is set correctly with both adamant and the project.

cd <project_dir>
admt env login
# Inside container:
cd src/components && redo style_all
cd src/components && redo test_all

Non-interactive command execution

Use admt for redo passthroughs and arbitrary container commands:

admt build [path]                   # redo all
admt test [path]                    # redo test
admt env exec "<arbitrary-command>" # Non-redo work inside the container

As a fallback -- for operations admt has not yet absorbed:

bash <project_dir>/docker/adamant_env.sh exec "cd /home/user/<project_name> && <command>"

Both forms use a cached environment snapshot so the second and subsequent calls restore in milliseconds instead of re-running the multi-second activation. admt owns its own snapshot (/tmp/admt/<project>/env_snapshot.sh + exec.sh); the legacy helper uses /tmp/.<project>_env_snapshot. Container restart invalidates both.

How the legacy helper works (kept as the underlying mechanism):

• env/activate saves export -p to /tmp/.<project>_env_snapshot after setup
• env/activate_from_snapshot loads the snapshot or falls back to full activate if none exists
• env/container_run.sh sources activate_from_snapshot and runs the command
• adamant_env.sh exec calls container_run.sh inside the container

Why snapshot-based activation is preferred over raw docker exec:

• Fast: snapshot activation is milliseconds vs seconds for full activate
• Correct: handles the ADAMANT_ENVIRONMENT_SET guard variable properly
• The base adamant image's .bashrc sources adamant/env/activate, which sets ADAMANT_ENVIRONMENT_SET. This guard variable prevents the project's activate from re-running. Both admt's proxy and adamant_env.sh exec handle this correctly; docker exec directly does not.

5. Set Up .gitignore

Recommended patterns:

# Build artifacts (redo creates build/ dirs everywhere)
**/build/

# Python
*.pyc
__pycache__/

# Alire (managed, not checked in)
/alire/
/config/
!/config/README.md
!/config/<project>.configuration.yaml

# OS/editor
.DS_Store
*.swp
*.tmp
~$*

# Vagrant/misc
.vagrant
.Trash*
.pyenv/
.tmp
.unison*
GNAT-*

The critical pattern is **/build/ -- redo creates build/ subdirectories in every source directory during compilation.

6. Directory Rules: .all_path and env.py

.all_path Marker Files

Every directory containing source files that should be discoverable by the build system must have an empty .all_path file. This includes:

• src/types/
• src/components/<each_component>/
• src/assembly/
• src/assembly/main/

The build system scans BUILD_ROOTS for .all_path files to build its source file index. Missing .all_path = invisible directory.

env.py (Python Path Configuration)

Each build root can have Python configuration activated via set_python_path.sh. Python files in later paths override earlier ones -- adamant is always first, so project-specific Python always wins.

Build Commands

admt build                                  # Build everything from any dir (redo all)
admt build build/bin/Linux/main.elf         # Native ELF (from main/ dir)
admt build run                              # Build and run (from main/ dir)
admt clean                                  # Remove all build artifacts
admt style --all                            # Check style across project

First Build Walkthrough

When you run admt build or build a target for the first time:

1. Environment check -- redo verifies BUILD_ROOTS and ADAMANT_CONFIGURATION_YAML are set
2. Code generation -- YAML model files are processed through Jinja templates to generate Ada specs/bodies. Configuration values from your YAML are substituted (e.g., {{ data_product_buffer_size }} → 32)
3. Dependency resolution -- redo scans .all_path directories across all BUILD_ROOTS, building a dependency graph
4. Compilation -- gprbuild compiles Ada sources using GPR files from redo/targets/gpr/
5. Linking -- produces ELF binary in build/bin/<Target>/

Expected first-build behavior:

• Takes several minutes (compiling all of adamant framework)
• Creates build/ directories throughout the source tree
• Downloads/builds alire dependencies if not cached
• Subsequent builds are incremental (much faster)

Multi-Project Setups

For projects that depend on both adamant and another shared library project:

# In env/activate, pass multiple paths separated by colons:
. $ADAMANT_DIR/env/activate $PROJECT_DIR:$OTHER_PROJECT_DIR

Or set BUILD_ROOTS manually before sourcing:

export BUILD_ROOTS="$ADAMANT_DIR:$SHARED_LIB_DIR:$PROJECT_DIR"
. $ADAMANT_DIR/env/activate

The order matters: later paths override earlier ones for Python configuration. Adamant is always prepended if not already present.

Adding Components

1. Create src/components/<name>/ with empty .all_path
2. Create <name>.component.yaml (model definition)
3. Run redo from the component dir -- generates Ada specs/bodies in build/
4. Copy generated templates to create your implementation

For full component model syntax, connector types, and implementation patterns: see adamant-component-dev.

Running Unit Tests

cd src/components/<name>/test && redo test   # Single component
cd src/components && redo test_all           # All components

Test directories do NOT have .all_path -- they use env.py (from environments import test). Test harness files are generated via redo templates and copied into the test dir. For test writing patterns: see adamant-testing.

Hardware Target Configuration

The Docker image includes cross-compilers for ARM and RISC-V. Targets are selected via GPR files in redo/targets/gpr/.

Project-specific target overrides: Projects can have their own redo/targets/ directory with custom linux.py (target class definitions) and gpr/ files that override or extend the framework's targets. This is how projects add custom GPR flags, linker options, or PROJECT_DIR references.

Pico and ARM targets subclass the base GPR and set Target, Runtime, and linker flags. The default.uf2.do script converts ELF to UF2 format for Pico flashing.

To build for a specific target, set TARGET in your main .do file or build directly:

redo build/bin/Pico/main.elf               # Cross-compile for Pico

Cross-compilation requires the matching alire crate pins in alire.toml (the Docker image has ARM toolchains pre-installed).

For build system internals and target subclassing: see adamant-build-system.

COSMOS Ground System Integration

To connect your assembly to COSMOS for telemetry and commanding, see adamant-cosmos-integration. Key steps: add CCSDS components to assembly, generate plugin via redo cosmos_config, build and load the gem.

Common Setup Errors and Fixes

Docker Image Details

ghcr.io/lasp/adamant:0.1 (~1.3GB) includes:

• GNAT native compiler (via alire)
• GNAT ARM ELF cross-compiler (via alire)
• GNATprove (SPARK formal verification)
• redo build system
• Python 3 + pip
• Standard development tools

Related Skills

• Build system: adamant-build-system
• Component dev: adamant-component-dev
• Testing: adamant-testing
• COSMOS: adamant-cosmos-integration
• Style: adamant-style -- run redo style_all to validate entire project