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: .. code-block:: markdown [![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-reqs: 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: .. code-block:: yaml 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: 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. .. _usage-oci-adjustments: With OCI Image Adjustments ^^^^^^^^^^^^^^^^^^^^^^^^^^ If you are modifying the pre-built OCI images or want to use your own images: .. code-block:: yaml 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}// 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: - - 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 :ref:`usage-oci-adjustments`, you can reference the built images in your jobs as follows: .. code-block:: yaml 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 :ref:`oci-build` works on all supported platforms and runner instances (since the Buildah image ships with QEMU), :ref:`meson-build` and :ref:`meson-test` 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 :ref:`oci-images` with :ref:`oci-build` 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).