README.cicd

> README.cicd: KDE Invent GitLab CI/CD pipelines
> SPDX-FileCopyrightText: 2024 Eric Dejouhanet <eric.dejouhanet@gmail.com>
> SPDX-License-Identifier: GPL-2.0-or-later

# KDE Invent Gitlab CI/CD pipelines

This documentation describes how the KDE Invent infrastructure is producing KStars/Ekos binaries.

## Continuous Integration

The KStars build recipe is based on `cmake`, see file `INSTALL` for manual build instructions. The `cmake` recipe is described
in multiple files (`CMakeLists.txt`) in the tree, and requires build dependencies, some of which are mandatory and some others optional.
Those dependencies are included in the (CI images provided by the KDE infrastructure)[https://invent.kde.org/sysadmin/ci-images].

Additional dependencies are configured in file `.kde-ci.yml`.
The (Wiki page of the CI Infrastructure)[https://community.kde.org/Infrastructure/Continuous_Integration_System] presents an
overview of the KDE integration factory.

The file `.kde-ci.yml` is parsed to feed (the metadata repository)[https://invent.kde.org/sysadmin/repo-metadata], which in turn
is used by build scripts in the CI infrastructure.

### Triggers

The KStars repository is configured to build its code in the following situations:
- When a Merge Request is pushed by a contributor
- When code is merged to the default branch (`master`)
- When a scheduled pipeline is run

The details of the configuration are implemented in `.gitlab-ci.yml`.
Check the (KStars | Build | Pipeline editor | Visualize)[https://invent.kde.org/education/kstars/-/ci/editor?branch_name=master&tab=1]
for a high-level visualisation of jobs.

Merge requests are built and tested for several platforms. The same build sequence is applied to the default branch when merging.

### Linux build

The Linux regular KDE Invent pipeline runs on an image of OpenSUSE Tumbleweed with Qt6.

This is the `suse_tumbleweed_qt610` job.
The legacy `suse_tumbleweed_qt515` job is present but currently disabled (`when: never`).

### Windows build

The Windows regular KDE Invent pipeline runs with the Qt6 Windows templates.

The job is named `windows_qt610` in `.gitlab-ci.yml`.

### Android build

The Android regular KDE Invent pipeline cannot be operated anymore with Qt5.
Android CI is currently not active in `.gitlab-ci.yml`.

### Custom build on Ubuntu24

Historically, there has been a need for end-to-end tests of Ekos to stabilise and secure behaviour against INDI drivers.
A custom build image is built from `docker/Dockerfile`, currently based on Ubuntu 24.04, supporting installation of external
dependencies *at the time of the build*. While inherently unstable due to the lack of versioning of those dependencies,
this allowed testing against nightly builds, mainly INDI nightly builds.

The active jobs are named `ubuntu_qt5` and `build-and-test-stable` in `.gitlab-ci.yml`. They are separate builds but use caching
to speed up the second build. Although this separation is unnecessary, this allows contributors to retrieve build artifacts
while the tests, quite lengthy, run in the background.

A `ubuntu_qt6` custom recipe is also present but currently disabled (`when: never`).

### CppCheck

Tool `cppcheck` runs and provides insight on code quality as a test report.
Its [documentation](https://cppcheck.sourceforge.io) lists the multiple situations that are detected.

There is currently no `cppcheck` job in `.gitlab-ci.yml`.

## Continuous Deployment

The jobs pertaining to deployment are triggered by pushes in specific branches of the KStars repository, declared in YAML files
(in the CI utilities repository)[https://invent.kde.org/sysadmin/ci-utilities/-/tree/master/signing?ref_type=heads].

Those jobs use (the tool "Craft")[https://community.kde.org/Craft] for building releases.
The (Craft recipes)[https://invent.kde.org/packaging/craft-blueprints-kde/], such as `applications/kstars`
or `libs/indilib`, describe the methods to use to build each application component.

Build images (make use of a meta-tool)[https://invent.kde.org/packaging/craftmaster/] named `CraftMaster`. This tool
parses the tree of dependencies, schedules build of components that are not actively cached, and installs their artifacts
in order to produce the final packaged application.

The (CI Notary service)[https://invent.kde.org/sysadmin/ci-notary-service] is then used to sign binaries for use on various delivery platforms.

The branch used for deployment is first registered in https://invent.kde.org/sysadmin/ci-utilities/ in `signing/buildpublisher-projects.yaml`
then in the other YAML databases for specific distributions. The following builds execute the deployment recipes in their own environments:

### Linux deployment

The Linux deployment build currently runs Flatpak publishing jobs (`flatpak-amd64` and `flatpak-arm64`) in `.gitlab-ci.yml`.
Craft-based Linux AppImage deployment is not currently configured in this pipeline.

### Windows deployment

The Windows deployment build runs in a Windows-based infrastructure using Craft recipes.
The related jobs are `craft_windows_qt6_x86_64` and `microsoftstore_qt6`.

The branch used for deployment is registered in https://invent.kde.org/sysadmin/ci-utilities/ in `signing/windowsbinariessigner-projects.yaml`
and `signing/microsoftstorepublisher-projects.yaml`.

The pipeline runs the signature procedure suitable for binaries to be deployed to the Microsoft Store.

### MacOS build and deployment

The MacOS deployment build runs in an Apple-based infrastructure using Craft recipes.
The related jobs are `craft_macos_qt6_x86_64` and `craft_macos_qt6_arm64`.

The branch used for deployment is registered in https://invent.kde.org/sysadmin/ci-utilities/ in `signing/macappsigner-projects.yaml`
and `signing/macappnotarizer-projects.yaml`.

The pipeline runs the signature procedure suitable for binaries to be deployed to the Apple Store.