Usage Overview

Add a badge to README

If you find this project useful, consider adding a badge to your repository’s README to let others know you’re using it. This is entirely optional, but it helps spread the word and makes it easier for others to discover the project.

You can add the following Markdown snippet to your README:

[![CI powered by ci-multiplatform](https://gitlab.com/riseproject/CI/ci-multiplatform/-/raw/main/doc/badge.svg)](https://gitlab.com/riseproject/CI/ci-multiplatform)

Feel free to adjust the badge style or placement as you like!

Top-level Requirements

To use the templates from this project, it is recommended to include the following clauses in your CI configuration.

Without OCI Image Adjustments

If you are not modifying the pre-built OCI images and want to use only the build system templates:

spec:
  inputs:
    active_target_pattern:
      description: |
        Regular expression to match the target for which the job should be
        activated. This is used to enable or disable specific targets.
      default: /linux-cross-.*|linux-native-.*|windows-cross-.*/
      type: string
---

# Example list of stages if you want to use all templates.
stages:
  - build
  - test
  - summary

variables:
  # OCI image global default configuration.
  OCI_REGISTRY_IMAGE: <path to the pre-built OCI image without a tag>
  OCI_TAG: latest
  OCI_NAME_FULL: ${OCI_REGISTRY_IMAGE}:${OCI_TAG}-${TARGET}

.ci-multiplatform-base:
  image:
    name: $OCI_NAME_FULL
  rules:
    # Enable specific targets based on a regular expression from CI input.
    - if: "$TARGET =~ $[[ inputs.active_target_pattern ]]"

The active_target_pattern input allows you to control which targets are activated in the CI jobs. The default pattern matches all Linux and Windows targets. Depending on your CI triggers, you can adjust the pattern to execute only specific targets, for example, for scheduled runs by modifying the input value.

The .ci-multiplatform-base virtual job is used by all template jobs. You may use a different name, but you will need to adjust the extends clause in the templates accordingly.

An example path to the pre-built OCI image: registry.gitlab.com/riseproject/ci/ci-multiplatform/debian/llvm-meson.

You can also add additional configuration to the base job if you have specific requirements.

With OCI Image Adjustments

If you are modifying the pre-built OCI images or want to use your own images:

spec:
  inputs:
    active_target_pattern:
      description: |
        Regular expression to match the target for which the job should be
        activated. This is used to enable or disable specific targets.
      default: /linux-cross-.*|linux-native-.*|windows-cross-.*/
      type: string
---

# Example list of stages if you want to use all templates.
stages:
  - oci
  - build
  - test
  - summary

variables:
  # OCI image global default configuration.
  OCI_REGISTRY_IMAGE: ${CI_REGISTRY}/<group>/<project-name>
  OCI_TAG: latest
  OCI_NAME_FULL: ${OCI_REGISTRY_IMAGE}/${CI_PROJECT_NAME}:${OCI_TAG}-${TARGET}

.ci-multiplatform-base:
  image:
    name: $OCI_NAME_FULL
  rules:
    # Enable specific targets based on a regular expression from CI input.
    - if: "$TARGET =~ $[[ inputs.active_target_pattern ]]"

workflow:
  rules:
    # Use a modified OCI image if building in a merge request and the OCI
    # image is affected by the MR.
    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'
      changes:
        paths:
          - <path to the file which instantiates the oci.yml template>
          - <path to the Containerfile and/or OCI context>
      variables:
        OCI_TAG: $CI_COMMIT_REF_SLUG
        OCI_REGISTRY_IMAGE: $CI_REGISTRY_IMAGE

The active_target_pattern input works the same as in the previous example, allowing you to control which targets are activated in the CI jobs.

OCI_REGISTRY_IMAGE should contain a hard-coded path to the main project, as the CI_REGISTRY_IMAGE variable changes in forks. If someone creates a fork of the project and does not modify the OCI image in the merge request, the pipeline will use the latest pre-built OCI image from the upstream repository.

The workflow.rules section allows you to build the OCI image only when it is affected by the merge request. It uses the changes clause to check if the OCI image is modified in the MR. If so, the pipeline will build the OCI image with the tag set to the MR branch name; otherwise, it will use the pre-built OCI image with the latest tag, making the pipeline faster and more efficient. For example, if you have the OCI image definition in the .gitlab-ci.d/oci directory, you can set the path as follows: .gitlab-ci.d/oci/**/*.

Using the images from the OCI stage

If you want to use only the OCI image builder templates (without the build system templates), after completing the base setup described in With OCI Image Adjustments, you can reference the built images in your jobs as follows:

test:
  stage: test
  extends: .ci-multiplatform-base
  needs: oci
  parallel:
    matrix:
      - TARGET:
        - linux-native-amd64
        - linux-native-riscv64
        - linux-native-arm64-v8
  script:
    - uname -a

Mind the usage of the .ci-multiplatform-base virtual job.

Runner Requirements

Warning

While OCI Image Build Template works on all supported platforms and runner instances (since the Buildah image ships with QEMU), Meson Build Template and Meson Test Template may not work on all CI runners. Please review the compatibility notes below.

For best results, your runner should meet the following requirements:

  • Runner type: docker

  • privileged flag enabled (see runner Advanced configuration).

  • QEMU with binfmt support (e.g., qemu-binfmt package on Ubuntu).

If the runner does not have the privileged flag enabled, building OCI Images with OCI Image Build Template will not be possible, as Buildah requires unshare capability (see Buildah issue).

GitLab.com Compatibility

Shared runners on GitLab.com cannot run images for these targets:

  • linux-native-mipsel

  • linux-native-ppc

  • linux-native-ppc64

Otherwise, all of the templates are supported. For runner tag details, see the Hosted Runners on Linux documentation.

This repository uses these tags for testing:

  • saas-linux-medium-amd64 for generic x86_64, targets requiring QEMU, and ARM32 targets.

  • saas-linux-small-arm64 for ARM64 targets.

Note

ARM64 runners may be unreliable for ARM32 images. For ARM32, use saas-linux-medium-amd64.

Freedesktop.org Compatibility

The Freedesktop.org (FDO) infrastructure supports all templates. It has three types of runners:

  • Fleeting runners (no tag, i.e., ""): basic x86_64 runners without QEMU (preferred if possible).

  • QEMU-enabled x86_64 runners (kvm tag).

  • ARM64 runners (aarch64 tag).