Skip to main content

Dalec Specification

Dalec YAML specification is a declarative format for building system packages and containers from those packages.

This section provides a high level overview of the Dalec YAML specification. For more detailed information, please see the applicable sections.

note

All Dalec spec YAMLs must start with # syntax=ghcr.io/azure/dalec/frontend:latest.

Dalec spec YAMLs are composed of the following sections:

Args section​

Args section is an optional section that is used to define the arguments that can be passed to the spec. These arguments can be used in the spec to define the version, commit, or any other fields.

args:
  VERSION: 1.0.0
  COMMIT: 55019c83b0fd51ef4ced8c29eec2c4847f896e74
  REVISION: 1

There are a few built-in arguments which, if present, Dalec will substitute values for. They are listed as examples in the following block:

args:
  TARGETOS:
  TARGETARCH:
  TARGETPLATFORM:
  TARGETVARIANT:

These arguments are set based on the default docker platform for the machine, unless the platform is overridden explicitly in the docker build with --platform. For example, upon invoking docker build on a Linux amd64 machine, we would have TARGETOS=linux, TARGETARCH=amd64, TARGETPLATFORM=linux/amd64.

note

No default value should be included for these build args. These args are opt-in. If you haven't listed them in the args section as shown above, Dalec will not substitute values for them.

Metadata section​

Metadata section is used to define the metadata of the spec. This metadata includes the name, packager, vendor, license, website, and description of the spec.

name: My-Package
license: Apache-2.0
description: This is a sample package
version: ${VERSION}
revision: ${REVISION}
packager: Dalec Authors
vendor: Dalec Authors
website: https://github.com/foo/bar
  • name: The name of the package.
  • license: The license of the package.
  • description: The description of the package.
  • version: The version of the package.
  • revision: The revision of the package.
  • packager: The packager of the package. This is an optional field.
  • vendor: The vendor of the package. This is an optional field.
  • website: The website of the package. This is an optional field.
tip

Any field at the top-level that begins with x- will be ignored by Dalec. This allows for custom fields to be added to the spec. For example, x-foo: bar. Any other field that is not recognized by Dalec will result in a validation error.

Targets section​

Targets section is used to define configuration per target. Each target can have its own configuration.

targets:
  mariner2:
    image:
      base: mcr.microsoft.com/cbl-mariner/distroless/minimal:2.0
      post:
        symlinks:
          /usr/bin/my-binary:
            path: /my-binary
    package_config:
      signer:
        image: azcutools.azurecr.io/azcu-dalec/signer:latest
  azlinux3:
    # same fields as above
  windowscross:
    # same fields as above

Valid targets are mariner2, azlinux3, windowscross.

For more information, please see Targets.

Image section​

Image section is used to define the base image and post processing for the image.

  • base: The base image for the target.
  • post: The post processing for the image, such as symlinks.

Package Config section​

Package Config section is used to define the package configuration for the target.

  • signer: The signer configuration for the package. This is used to sign the package. For more information, please see Signing Packages.

Sources section​

Sources section is used to define the sources for the spec. These sources can be used to define the source code, patches, or any other files needed for the spec.

sources:
  foo:
    git:
      url: https://github.com/foo/bar.git
      commit: ${COMMIT}
      keepGitDir: true
    generate:
    - gomod: {}
  foo-patch:
    http:
      url: https://example.com/foo.patch
  foo-inline:
    inline:
      - name: my-script
        content: |
          #!/bin/sh
          echo "Hello, World!"
  foo-context:
    context: {}

For more information, please see Sources.

Dependencies section​

The dependencies section is used to define the dependencies for the spec. These dependencies can be used to define the build dependencies, runtime dependencies, or any other dependencies needed for the package.

tip

Dependencies can be defined at the root level or under a target. If defined under a target, the dependencies will only be used for that target. Dependencies under a target will override dependencies at the root level. For more information, please see Targets.

dependencies:
  build:
    - golang
    - gcc
  runtime:
    - libfoo
    - libbar

Sometimes you may need to add extra repositories in order to fulfill the specified dependencies. You can do this by adding these to the extra_repos field. The extra_repos field takes a list of repository configurations with optional public key data and optional repo data (e.g. the actual data of a repository). See repositories for more details on repository configs

Build section​

Build section is used to define the build steps for the spec. These build steps can be used to define the build commands, environment variables, or any other build configuration needed for the package.

build:
  env:
    TAG: v${VERSION}
    GOPROXY: direct
    CGO_ENABLED: "0"
    GOOS: ${TARGETOS}
  steps:
    - command: |
        go build -ldflags "-s -w -X github.com/foo/bar/version.Version=${TAG}" -o /out/my-binary ./cmd/my-binary
  • env: The environment variables for the build.
  • steps: The build steps for the package.
  • network_mode: Set the network mode to use for build steps (accepts: empty, none, sandbox)
tip

TARGETOS is a built-in argument that Dalec will substitute with the target OS value. For more information, please see Args section.

tip

Set network_mode to sandbox to allow internet access during build

Artifacts section​

Artifacts section is used to define the artifacts for the spec. These artifacts can be used to define the output of the build, such as the package or container image.

artifacts:
  binaries:
     foo/my-binary: {}
  manpages:
    src/man/man8/*:
      subpath: man8

For more information, please see Artifacts

Tests section​

Tests section is used to define the tests for the spec. These tests can be used to define the test cases, steps, or any other tests needed for the package.

tests:
  - name: check permissions
    files:
      /usr/bin/my-binary:
        permissions: 0755
  - name: version reporting
    steps:
      - command: my-binary --version
        stdout:
          starts_with: "my-binary version ${VERSION}"
          contains:
            - "libseccomp: "
        stderr:
          empty: true

For more information, please see Testing.