diff --git a/doc/languages-frameworks/qt.xml b/doc/languages-frameworks/qt.xml
index b9b605b81da1..032cdd9945b3 100644
--- a/doc/languages-frameworks/qt.xml
+++ b/doc/languages-frameworks/qt.xml
@@ -4,71 +4,173 @@
Qt
- 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
- until their support window ends. The most important consideration in
- packaging Qt-based software is ensuring that each package and all its
- dependencies use the same version of Qt 5; this consideration motivates most
- of the tools described below.
+ This section describes the differences between Nix expressions for Qt
+ libraries and applications and Nix expressions for other C++ software. Some
+ knowledge of the latter is assumed. There are primarily two problems which
+ the Qt infrastructure is designed to address: ensuring consistent versioning
+ of all dependencies and finding dependencies at runtime.
-
- Packaging Libraries for Nixpkgs
+
+ Nix expression for a Qt package (<filename>default.nix</filename>)
+
+{ mkDerivation, lib, qtbase }:
-
- Whenever possible, libraries that use Qt 5 should be built with each
- available version. Packages providing libraries should be added to the
- top-level function mkLibsForQt5, which is used to build a
- set of libraries for every Qt 5 version. A special
- callPackage function is used in this scope to ensure that
- the entire dependency tree uses the same Qt 5 version. Import dependencies
- unqualified, i.e., qtbase not
- qt5.qtbase. Do not import a package
- set such as qt5 or libsForQt5.
-
+mkDerivation {
+ pname = "myapp";
+ version = "1.0";
-
- 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.
-
-
+ buildInputs = [ qtbase ];
+}
+
+
-
- Packaging Applications for Nixpkgs
+
+
+
+ Import mkDerivation and Qt (such as
+ qtbase modules directly. Do not
+ import Qt package sets; the Qt versions of dependencies may not be
+ coherent, causing build and runtime failures.
+
+
+
+
+ Use mkDerivation instead of
+ stdenv.mkDerivation. mkDerivation
+ is a wrapper around stdenv.mkDerivation which
+ applies some Qt-specific settings.
+ This deriver accepts the same arguments as
+ stdenv.mkDerivation; refer to
+ for details.
+
+
+ To use another deriver instead of
+ stdenv.mkDerivation, use
+ mkDerivationWith:
+
+mkDerivationWith myDeriver {
+ # ...
+}
+
+ If you cannot use mkDerivationWith, please refer to
+ .
+
+
+
+
+ mkDerivation accepts the same arguments as
+ stdenv.mkDerivation, such as
+ buildInputs.
+
+
+
-
- Call your application expression using
- libsForQt5.callPackage instead of
- callPackage. Import dependencies unqualified, i.e.,
- qtbase not qt5.qtbase. Do
- not import a package set such as qt5 or
- libsForQt5.
-
+
+ Locating runtime dependencies
+
+ Qt applications need to be wrapped to find runtime dependencies. If you
+ cannot use mkDerivation or
+ mkDerivationWith above, include
+ wrapQtAppsHook in nativeBuildInputs:
+
+stdenv.mkDerivation {
+ # ...
-
- Qt 5 maintains strict backward compatibility, so it is generally best to
- build an application package against the latest version using 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. If a package must be pinned to
- an older Qt version, be sure to file a bug upstream; because Qt is strictly
- backwards-compatible, any incompatibility is by definition a bug in the
- application.
-
+ nativeBuildInputs = [ wrapQtAppsHook ];
+}
+
+
+
+
+
+ Entries added to qtWrapperArgs are used to modify the
+ wrappers created by wrapQtAppsHook. The entries are
+ passed as arguments to .
+
+mkDerivation {
+ # ...
+
+ qtWrapperArgs = [ ''--prefix PATH : /path/to/bin'' ];
+}
+
+
+
+
+ Set dontWrapQtApps to stop applications from being
+ wrapped automatically. It is required to wrap applications manually with
+ wrapQtApp, using the syntax of
+ :
+
+mkDerivation {
+ # ...
+
+ dontWrapQtApps = true;
+ preFixup = ''
+ wrapQtApp "$out/bin/myapp" --prefix PATH : /path/to/bin
+ '';
+}
+
+
+
+
+ Libraries are built with every available version of Qt. Use the meta.broken
+ attribute to disable the package for unsupported Qt versions:
+
+mkDerivation {
+ # ...
+
+ # Disable this library with Qt < 5.9.0
+ meta.broken = builtins.compareVersions qtbase.version "5.9.0" < 0;
+}
+
+
+
+
+ Adding a library to Nixpkgs
+
+ Add a Qt library to all-packages.nix by adding it to the
+ collection inside mkLibsForQt5. This ensures that the
+ library is built with every available version of Qt as needed.
+
+ Adding a Qt library to <filename>all-packages.nix</filename>
+
+{
+ # ...
+
+ mkLibsForQt5 = self: with self; {
+ # ...
+
+ mylib = callPackage ../path/to/mylib {};
+ };
+
+ # ...
+}
+
+
+
+
+
+
+ Adding an application to Nixpkgs
+
+ Add a Qt application to all-packages.nix using
+ libsForQt5.callPackage instead of the usual
+ callPackage. The former ensures that all dependencies
+ are built with the same version of Qt.
+
+ Adding a Qt application to <filename>all-packages.nix</filename>
+
+{
+ # ...
+
+ myapp = libsForQt5.callPackage ../path/to/myapp/ {};
+
+ # ...
+}
+
+
+
+
-
- When testing applications in Nixpkgs, it is a common practice to build the
- package with nix-build and run it using the created
- symbolic link. This will not work with Qt applications, however, because
- they have many hard runtime requirements that can only be guaranteed if the
- package is actually installed. To test a Qt application, install it with
- nix-env or run it inside nix-shell.
-
-