Platform grammar¶

Platform grammar describes statements that select a project file’s key values based on the build’s target platform. This allows for an image to be catered to the needs of each platform declared in its project file.

`for` statements¶

The for statement selects key values based on the build’s target platform, and accepts a single platform as its argument.

<key>:
  - for <platform-1>: <value-1>
  [...]
  - for <platform-n>: <value-n>

If a for statement matches against the build’s target platform, its value is assigned.

Similar logic applies when assigning values to lists.

<key>:
  - for <platform-1>:
    - <value-1>
  [...]
  - for <platform-n>:
    - <value-n>
  - <default>

If a for statement matches against the build’s target platform, its values are appended to the list. Values that aren’t nested in a for statement are appended regardless of the target platform.

`any` platform¶

any is a platform that, when included in a for statement, will always match against the build’s target platform.

<key>:
  - for <platform-1>: <value-1>
  - for any: <default>

If no other for statements match against the build’s target platform, the for any statement’s value is assigned. If the key expects a single value and multiple for statements match against the build’s target platform, the value of the first match is assigned. If a for any statement is included in a list, its items will always be appended.

`else` clauses¶

A for statement can be followed by an optional else clause.

<key>:
  - for <platform-1>: <value-1>
  - else: <default>

The body of the else clause is only assigned if the preceding for statement doesn’t match against the build’s target platform.

An else clause only considers the outcome of the for statement that comes immediately before it.

imagecraft.yaml¶

platforms:
  laptop:
    build-on: amd64
    build-for: amd64
  dev-board:
    build-on: [amd64, arm64]
    build-for: arm64

[...]

build-packages:
  - for laptop:
    - git
  - for dev-board:
    - python3-dev
  - else:
    - make

For a build targeting the laptop platform, the build-packages key would include both git and make. Despite for laptop matching, the else statement’s values are still appended, as the for dev-board statement didn’t match.

else clauses can be placed after any for statement, regardless of its position. The following build-packages declaration yields the same results as the previous example:

imagecraft.yaml¶

[...]

build-packages:
  - for dev-board:
    - python3-dev
  - else:
    - make
  - for laptop:
    - git

Example¶

The following project file snippet declares two platforms, laptop and dev-board, and platform-specific values for the source and build-environment keys in the ffmpeg part.

imagecraft.yaml¶

platforms:
  laptop:
    build-on: amd64
    build-for: amd64
  dev-board:
    build-on: [amd64, arm64]
    build-for: arm64

[...]

parts:
  ffmpeg:
    plugin: dump
    source:
    - for laptop: https://github.com/ffbinaries/ffbinaries-prebuilt/releases/download/v6.1/ffmpeg-6.1-linux-64.zip
    - for dev-board: https://github.com/ffbinaries/ffbinaries-prebuilt/releases/download/v6.1/ffmpeg-6.1-linux-arm-64.zip
    build-environment:
    - for laptop:
      - DISPLAY: Idle
    - for dev-board:
      - BOARD_STATUS: Ready
    - NAME: FFmpeg part
[...]

The build for the laptop platform pulls the x64 source for the ffmpeg part and sets the DISPLAY build environment variable to Idle. The build for the dev-board platform pulls the ARM64 source and sets the BOARD_STATUS build environment variable to Ready. The builds for both platforms set the NAME environment variable to FFmpeg part.

After the grammar is resolved, the two builds are equivalent to those produced by the following single-platform project files:

Platform grammar¶

for statements¶

any platform¶

else clauses¶

Example¶

`for` statements¶

`any` platform¶

`else` clauses¶