Static builds of KDE Frameworks and KDE applications

Being able to build our libraries and applications statically has been on the wishlist since a long time, and recently we made some progress in that direction again. Similar to the the recent Android integration improvements this is also a direct result of Akademy.

Reviving the CI

We had CI for static builds during the 5 era, but we lost quite a bit of coverage there during the transition to 6. However, what we had were only static builds of KDE libraries against a shared build of Qt. That finds some but by far not all issues related to static builds.

The new setup now actually has a static Qt6 to build against, which forces us to also sort out plugin integration correctly. While it is a bit more work to get back to the desired level of CI coverage that way, we will get to a much better result.

Static initialization and CMake

A common problem in static builds is initialization code that is run on shared library loading, as that simply doesn’t exist in static builds, and unless you know what you are doing that will usually be silently dropped from the final executable.

This has previously resulted in various workarounds, such as explicit initialization API (e.g. Q_INIT_RESOURCE), which is easy to miss. With Qt 6 having switched to CMake there’s a new option now though, so-called object libraries. Those are used as implementation details to inject the initialization code from static libraries into the final executable.

From a consumer point of view you get the same behavior as with shared libraries: you link against it and initialization just works. Behind the scenes this adds quite a bit of complexity to the build system though, which then sometimes leaks through into our build system code as well.

The probably most common case is qt6_add_resources. Qt resources need initialization code, so the target they are added to gets another dependency attached to it, an object library containing the initialization.

If that target is a library the additional object libraries need to be installed and exported via CMake as well, to make those available to consumer code (ECM support for this).

add_library(MyLib)
qt6_add_resources(MyLib OUTPUT_TARGETS _out_targets ...)
install(TARGETS MyLib ${_out_targets} EXPORT MyLibTargets ...)

The OUTPUT_TARGETS part is the new thing to add here (example). Another such case are custom shaders (via qt6_add_shaders), and of course QML modules (more on those below).

Installing QML modules

QML modules created with ecm_add_qml_module also produce object library targets, but since that macro works on a higher level we can handle more of that automatically (ECM MR).

ecm_add_qml_module(mymodule URI "org.kde.mymodule" ... INSTALLED_PLUGIN_TARGET KF6::mymodule)
...
ecm_finalize_qml_module(mymodule EXPORT KF6MyModuleTargets)

The EXPORT argument to ecm_finalize_qml_module is the new part here. This takes care both of installing object libraries as well as exporting the QML module itself in the installed CMake configuration file. The latter is needed for statically linking QML modules into the application (see below).

When using ALIAS targets (common in KDE Frameworks, much less common outside of that) we also might need the INSTALLED_PLUGIN_TARGET argument for ecm_add_qml_module(), to make sure the module target name matches the installed alias. That’s not new, but has little practical impact outside of static linking so we have been a bit sloppy there (simple example, complex example).

Importing QML modules

Linking QML modules into the final application binary got a lot easier with Qt 6, thanks to qmlimportscanner.

add_executable(myapp)
ecm_add_qml_module(myapp ...)
...
if (NOT QT6_IS_SHARED_LIBS_BUILD)
    qt6_import_qml_plugins(myapp)
endif()

That’s it, no more Q_IMPORT_PLUGIN macros or manually listing modules to link. There’s less tolerance for mistakes in the CMake and QML module metadata now though, anything incomplete or missing there will give you linker failures or module loading errors at runtime (see also ECM support for additional import search paths).

Outlook

Since Akademy almost 50 merge requests have been submitted related to this, most of which have already been integrated. With all that it’s possible now to build and run Alligator against a static Qt. Alligator was the first milestone we had picked for this during Akademy, due to being sufficiently complex to prove the viability of all this while not having dependencies that could be adding significant additional challenges on their own (such as the multimedia stack).

However, this work has been mostly done on desktop Linux, and while that allowed for rapid progress it’s the platform this is least interesting for. We yet have to reproduce this on Android, where it probably should bring the most immediate benefit, and of course this removes a big obstacle for potential support of iOS (as Qt can only be linked statically there).