From c1fc4af9ae25998888495cdc8b6d98fc2ec9474d Mon Sep 17 00:00:00 2001 From: Thomas Tuegel Date: Sat, 25 Feb 2017 11:16:31 -0600 Subject: Update Qt and KDE documentation - Describe the new `libsForQt5.callPackage` interface - Emphasize that Qt dependencies must be imported unqualified - Describe the new `kdeWrapper` wrapper generator --- doc/languages-frameworks/qt.xml | 62 +++++++++-------------------------------- 1 file changed, 13 insertions(+), 49 deletions(-) diff --git a/doc/languages-frameworks/qt.xml b/doc/languages-frameworks/qt.xml index 093c33c25a1..b6c8f0e899e 100644 --- a/doc/languages-frameworks/qt.xml +++ b/doc/languages-frameworks/qt.xml @@ -2,67 +2,31 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-language-qt"> -Qt +Qt and KDE -The information in this section applies to Qt 5.5 and later. - -Qt is an application development toolkit for C++. Although it is -not a distinct programming language, there are special considerations -for packaging Qt-based programs and libraries. A small set of tools -and conventions has grown out of these considerations. +Qt is a comprehensive desktop and mobile application development toolkit for C++. Legacy support is available for Qt 3 and Qt 4, but all current development uses Qt 5. The Qt 5 packages in Nixpkgs are updated frequently to take advantage of new features, but older versions are typically retained to support packages that may not be compatible with the latest version. When packaging applications and libraries for Nixpkgs, it is important to ensure that compatible versions of Qt 5 are used throughout; this consideration motivates the tools described below.
Libraries -Packages that provide libraries should be listed in -qt5LibsFun so that the library is built with each -Qt version. A set of packages is provided for each version of Qt; for -example, qt5Libs always provides libraries built -with the latest version, qt55Libs provides -libraries built with Qt 5.5, and so on. To avoid version conflicts, no -top-level attributes are created for these packages. +Libraries that depend on Qt 5 should be built with each available version to avoid linking a dependent package against incompatible versions of Qt 5. (Although Qt 5 maintains backward ABI compatibility, linking against multiple versions at once is generally not possible; at best it will lead to runtime faults.) Packages that provide libraries should be added to the top-level function mkLibsForQt5, which is used to build a set of libraries for every Qt 5 version. The callPackage provided in this scope will ensure that only one Qt version will be used throughout the dependency tree. Dependencies should be imported unqualified, i.e. qtbase not qt5.qtbase, so that callPackage can do its work. Do not import a package set such as qt5 or libsForQt5 into your package; although it may work fine in the moment, it could well break at the next Qt update. + +If a library does not support a particular version of Qt 5, it is best to mark it as broken by setting its meta.broken attribute. A package may be marked broken for certain versions by testing the qtbase.version attribute, which will always give the current Qt 5 version.
-
Programs - -Application packages do not need to be built with every Qt -version. To ensure consistency between the package's dependencies, -call the package with qt5Libs.callPackage instead -of the usual callPackage. An older version may be -selected in case of incompatibility. For example, to build with Qt -5.5, call the package with -qt55Libs.callPackage. - -Several environment variables must be set at runtime for Qt -applications to function correctly, including: - - - QT_PLUGIN_PATH - QML_IMPORT_PATH - QML2_IMPORT_PATH - XDG_DATA_DIRS - - -To ensure that these are set correctly, the program must be wrapped by -invoking wrapQtProgram program -during installation (for example, during -fixupPhase). wrapQtProgram -accepts the same options as makeWrapper. - +
Applications + +Applications generally do not need to be built with every Qt version because they do not provide any libraries for dependent packages to link against. The primary consideration is merely ensuring that the application itself and its dependencies are linked against only one version of Qt. To call your application expression, use libsForQt5.callPackage instead of callPackage. Dependencies should be imported unqualified, i.e. qtbase not qt5.qtbase. Do not import a package set such as qt5 or libsForQt5 into your package; although it may work fine in the moment, it could well break at the next Qt update. + +It is generally best to build an application package against the libsForQt5 library set. In case a package does not build with the latest Qt version, it is possible to pick a set pinned to a particular version, e.g. libsForQt55 for Qt 5.5, if that is the latest version the package supports. + +Qt-based applications require that several paths be set at runtime. This is accomplished by wrapping the provided executables in a package with wrapQtProgram or makeQtWrapper during the postFixup phase. To use the wrapper generators, add makeQtWrapper to nativeBuildInputs. The wrapper generators support the same options as wrapProgram and makeWrapper respectively. It is usually only necessary to generate wrappers for programs intended to be invoked by the user.
KDE -Many of the considerations above also apply to KDE packages, -especially the need to set the correct environment variables at -runtime. To ensure that this is done, invoke wrapKDEProgram -program during -installation. wrapKDEProgram also generates a -ksycoca database so that required data and services -can be found. Like its Qt counterpart, -wrapKDEProgram accepts the same options as -makeWrapper. +The KDE Frameworks are a set of libraries for Qt 5 which form the basis of the Plasma desktop environment and the KDE Applications suite. Packaging a Frameworks-based library does not require any steps beyond those described above for general Qt-based libraries. Frameworks-based applications should not use makeQtWrapper; instead, use kdeWrapper to create the necessary wrappers: kdeWrapper { unwrapped = expr; targets = exes; }, where expr is the un-wrapped package expression and exes is a list of strings giving the relative paths to programs in the package which should be wrapped.
-- cgit 1.4.1