Skip to main content

0.27.0

Configuration changes​

New top-level source_date_epoch field​

Set a fixed Unix timestamp for reproducible extension image builds:

source_date_epoch: 1700000000

When set, this value is passed to mksquashfs and mkfs.erofs as the source timestamp, ensuring that images built from the same inputs produce identical bytes regardless of when the build runs. Defaults to 0 when not specified.

Extension filesystem field​

Choose the filesystem format for extension images:

extensions:
  my-app:
    version: '1.0.0'
    filesystem: erofs # or 'squashfs' (default)

Supported values: squashfs (default) and erofs. Both formats produce a .raw image file. erofs offers better random-access read performance and smaller images for certain workloads.

Extension var_files field​

Declare glob patterns for files within an extension's sysroot that belong on the var partition rather than in the read-only extension image:

extensions:
  docker-runtime:
    version: '1.0.0'
    types: [sysext]
    var_files:
      - var/lib/docker/**

Files matching these patterns are excluded from the .raw image during avocado ext image and are instead expected to live on the writable var partition at runtime. This is how persistent runtime state (Docker image layers, database files, caches) is handled without polluting the immutable system image.

Extension docker_images field​

Declare Docker images to pull and cache onto the var partition at build time. This primes a portable Docker image cache so containers can start on first boot without internet access:

extensions:
  my-app:
    version: '1.0.0'
    types: [sysext]
    docker_images:
      - image: docker.io/library/redis
        tag: '7-alpine'
      - image: docker.io/library/nginx
        tag: '1.25'

When any extension in the runtime declares docker_images, the CLI automatically adds --privileged to the SDK container args and starts a temporary dockerd instance inside the container to pull the images into a Docker data-root on the var partition staging area. The var partition is then seeded with a pre-populated image cache.

Each entry must specify both image (the full image reference) and tag.

Runtime var_files field​

Seed static files onto the var partition at build time by mapping source paths (relative to src_dir) to destination paths on the var partition:

runtimes:
  dev:
    extensions: [my-app]
    packages:
      avocado-runtime: '*'
    var_files:
      - source: config/app-defaults/
        dest: lib/myapp/
      - source: certs/device.pem
        dest: lib/myapp/certs/device.pem

source is a path relative to src_dir. dest is relative to the var partition root (e.g., lib/myapp/ maps to /var/lib/myapp/ on the device).

Runtime kernel compile mode​

Runtimes already supported kernel.package for installing a pre-built kernel RPM. The kernel.compile + kernel.install mode is now documented and fully supported in the CLI build pipeline:

runtimes:
  dev:
    kernel:
      compile: my-kernel # references sdk.compile.my-kernel
      install: kernel-install.sh

sdk:
  compile:
    my-kernel:
      compile: kernel-compile.sh
      packages:
        libelf1: '*'

When avocado build encounters a runtime with a kernel.compile section it:

  1. Runs the referenced sdk.compile section (your compile script).
  2. Runs the install script with $AVOCADO_RUNTIME_BUILD_DIR set to the runtime's build directory.
  3. Proceeds with normal runtime assembly.

See the custom kernel guide for a complete walkthrough.

SDK compile package block​

Add a package block to any sdk.compile section to enable avocado sdk package for that section:

sdk:
  compile:
    my-lib:
      compile: compile.sh
      clean: clean.sh
      packages:
        openssl-dev: '*'
      package:
        name: my-lib # defaults to section name
        version: '1.2.3' # required, semver
        release: '1' # defaults to '1'
        install: pkg-install.sh # required, stages files to $DESTDIR
        summary: 'My shared library'
        description: 'A cross-compiled shared library for the target.'
        license: MIT
        vendor: Acme Corp
        url: https://example.com/my-lib
        requires:
          - openssl >= 3.0
        # Optional sub-package splitting (Yocto-style)
        split:
          my-lib-dev:
            summary: 'Development headers for my-lib'
            files:
              - usr/include/**
              - usr/lib/*.a

See the packaging section of the cross-compilation guide for a complete example.

New commands​

avocado sdk package​

Package the output of a compiled SDK section into one or more architecture-specific RPMs:

avocado sdk package my-lib
avocado sdk package my-lib --out ./dist/

The compile section must have a package block (see above). The RPM is created inside the SDK container. Use --out <dir> to copy the resulting RPM(s) to a host directory.

Package a compiled SDK section into an RPM

Usage: avocado sdk package [OPTIONS] <SECTION>

Arguments:
  <SECTION>  Compile section to package (must have a 'package' block in config)

Options:
  -C, --config <CONFIG>                 Path to avocado.yaml configuration file [default: avocado.yaml]
  -v, --verbose                         Enable verbose output
  -t, --target <TARGET>                 Target architecture
      --out <OUT_DIR>                   Output directory on host for the built RPM(s)
      --container-arg <CONTAINER_ARGS>  Additional arguments to pass to the container runtime
      --dnf-arg <DNF_ARGS>              Additional arguments to pass to DNF commands
      --sdk-arch <ARCH>                 SDK container architecture for cross-arch emulation
  -h, --help                            Print help

Updated commands​

avocado ext image — --out flag and filesystem/var_files awareness​

The ext image command now accepts --out <dir> to copy the resulting .raw file to a host directory:

avocado ext image my-app --out ./dist/

The command also respects the extension's filesystem and var_files configuration:

  • filesystem: erofs causes mkfs.erofs to be used instead of mksquashfs
  • Files matching var_files patterns are excluded from the image

avocado ext package — now packages source directory​

avocado ext package previously required the extension to be built first (it packaged the built sysroot). It now packages the extension source directory directly and no longer requires a prior avocado ext build. A warning is printed reminding you to verify the build before publishing.

Positional NAME argument for ext and runtime subcommands​

All avocado ext * and avocado runtime * subcommands (except dnf) now accept the extension or runtime name as a positional argument instead of requiring -e/-r:

# New positional style (preferred)
avocado ext build my-app
avocado runtime build dev
avocado runtime provision dev

# Flag style still works
avocado ext build -e my-app
avocado runtime build -r dev

The -e/--extension and -r/--runtime flags are retained for backwards compatibility. avocado ext dnf and avocado runtime dnf are unchanged and still require the flag.

Improvements​

  • Docker image priming (docker_images) automatically adds --privileged to the container args for the runtime build — no manual override required.
  • The var partition staging area is now populated from both runtime var_files mappings and extension docker_images entries in a single build pass.
  • Reproducible images: source_date_epoch is threaded through both squashfs and erofs image creation, enabling bit-for-bit reproducible extension images.