OpenMiInk/third_party/krita-deps-management/how-to-work-with-package-aliases.md

How to work with package aliases

A pacakge alias is a "flavour" of a package that can substitute a normal package. For example, "ext_qt" package may have multiple flavours, like "ext_qt-debug", "ext_qt-asan" or "ext_qt-quickcontrols2". The main requirement for a package flavour is full binary compatibility with the original package. That is, packages depending on the original package much be able to consume a flavour package without full recompilation.

We use package flavours for several purposes:

• provide a debugging versions of a package (or ASAN-capable)
• build a package with a different set of flags, needed for a specific merge request

Create a flavour of a package

Imagine we would like to create a flavour of a Qt package. To implement that we need to do the follwoing:

1. Add a CMake option in ext_qt/CMakeLists.txt. Make sure that the option is disabled by default.

if (QT_ENABLE_MY_OPTION)
    # TODO: do something that changes the build process of Qt
endif ()

2. Create a separate folder for your flavour of the package (ext_qt-myoption) and add a special .kde-ci-override.yml file with the follwoing content:

Options:
  cmake-options: "-DQT_ENABLE_MY_OPTION=ON"

3. Create metadata for the new package flavour:

   1. Copy repo-metadata/projects-invent/base/qt folder into repo-metadata/projects-invent/base/qt-myoption

   2. Edit metadata.yml any replace all qt into qt-myoption

   3. Make sure that repopath is also changes, since this field is used as a unique key by the scripts internally

   4. Add line reuse-directory: ext_qt to make sure the project reuses the recipe of the main package

      When package is being built, the build script will copy the content of ext_qt into ext_qt-myoption and apply the cahnges from .kde-ci-override.yml to .kde-ci.yml, which was copied from the original project.

4. Add the package flavour to latest/developer-packages.yml seed file, to make sure it is rebuilt on full rebuilds.

5. Build the newly added package:

   1. Open the pipeline job custom_publish_<platform> (click on the name, not on the "start" button)

   2. On the job's page set the job input:

      • input: KRITA_STAGE_DEP
      • value: base/qt-myoption

   3. Start the job

Connect the package flavour to the Krita build

After the package flavour has been built, you need to instruct Krita to deploy it during the build process.

1. Open .kde-ci.yml file in Krita repository

2. Add the alias statement to substiture ext_qt package with your custom flavour ext_qt-myoption:

PackageAliases:
  ext_qt: ext_qt-myoption

3. Save and push into your branch/MR. All CI jobs will now use ext_qt-myoption package when building your MR.

Note on paltform-specific flavours

If your flavour is available only on a specifc platform, you can add it via declaring an environment variable in the corresponding jobs in .gitlab-ci.yml file in Krita repository:

.windows-build-base:
  variables:
    KDECI_PACKAGE_ALIASES_YAML: "{ ext_qt : ext_qt-myoption }"

Though this method it not recommended, since it makes it difficult to reproduce the environment locally.

Note on merging package flavours into master

Please do not merge flavoured packaged into master! It may break development environment for people and create a lot of troubles for people, who are not familiar with the changes. Make sure that all your changes are merged into "mainstream" package before the MR is merged into master.