nixpkgs: remark about running Qt applications

1 files changed, 46 insertions, 20 deletions

diff --git a/doc/languages-frameworks/qt.xml b/doc/languages-frameworks/qt.xml
index 4193fc5f16e..1dbbb5341ba 100644
--- a/doc/languages-frameworks/qt.xml
+++ b/doc/languages-frameworks/qt.xml
@@ -2,29 +2,55 @@
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xml:id="sec-language-qt">
 
-<title>Qt and KDE</title>
-
-<para>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.</para>
-
-<section xml:id="ssec-qt-libraries"><title>Libraries</title>
-
-<para>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 <varname>mkLibsForQt5</varname>, which is used to build a set of libraries for every Qt 5 version. The <varname>callPackage</varname> 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. <literal>qtbase</literal> not <literal>qt5.qtbase</literal>, so that <varname>callPackage</varname> can do its work. <emphasis>Do not</emphasis> import a package set such as <literal>qt5</literal> or <literal>libsForQt5</literal> into your package; although it may work fine in the moment, it could well break at the next Qt update.</para>
-
-<para>If a library does not support a particular version of Qt 5, it is best to mark it as broken by setting its <literal>meta.broken</literal> attribute. A package may be marked broken for certain versions by testing the <literal>qtbase.version</literal> attribute, which will always give the current Qt 5 version.</para>
-
-</section>
-
-<section xml:id="ssec-qt-applications"><title>Applications</title>
-
-<para>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 <literal>libsForQt5.callPackage</literal> instead of <literal>callPackage</literal>. Dependencies should be imported unqualified, i.e. <literal>qtbase</literal> not <literal>qt5.qtbase</literal>. <emphasis>Do not</emphasis> import a package set such as <literal>qt5</literal> or <literal>libsForQt5</literal> into your package; although it may work fine in the moment, it could well break at the next Qt update.</para>
-
-<para>It is generally best to build an application package against the <varname>libsForQt5</varname> 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. <varname>libsForQt55</varname> for Qt 5.5, if that is the latest version the package supports.</para>
+<title>Qt</title>
+
+<para>
+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.
+</para>
+
+<section xml:id="ssec-qt-libraries"><title>Packaging Libraries for Nixpkgs</title>
+
+<para>
+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 <varname>mkLibsForQt5</varname>,
+which is used to build a set of libraries for every Qt 5 version.
+A special <varname>callPackage</varname> function is used in this scope to ensure that the entire dependency tree uses the same Qt 5 version.
+Import dependencies unqualified, i.e., <literal>qtbase</literal> not <literal>qt5.qtbase</literal>.
+<emphasis>Do not</emphasis> import a package set such as <literal>qt5</literal> or <literal>libsForQt5</literal>.
+</para>
+
+<para>
+If a library does not support a particular version of Qt 5, it is best to mark it as broken by setting its <literal>meta.broken</literal> attribute.
+A package may be marked broken for certain versions by testing the <literal>qtbase.version</literal> attribute, which will always give the current Qt 5 version.
+</para>
 
 </section>
 
-<section xml:id="ssec-qt-kde"><title>KDE</title>
-
-<para>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 package does not require any steps beyond those described above for general Qt-based packages.</para>
+<section xml:id="ssec-qt-applications"><title>Packaging Applications for Nixpkgs</title>
+
+<para>
+Call your application expression using <literal>libsForQt5.callPackage</literal> instead of <literal>callPackage</literal>.
+Import dependencies unqualified, i.e., <literal>qtbase</literal> not <literal>qt5.qtbase</literal>.
+<emphasis>Do not</emphasis> import a package set such as <literal>qt5</literal> or <literal>libsForQt5</literal>.
+</para>
+
+<para>
+Qt 5 maintains strict backward compatibility, so it is generally best to build an application package against the latest version using the <varname>libsForQt5</varname> 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. <varname>libsForQt55</varname> 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.
+</para>
+
+<para>
+When testing applications in Nixpkgs, it is a common practice to build the package with <literal>nix-build</literal> 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 <literal>nix-env</literal> or run it inside <literal>nix-shell</literal>.
+</para>
 
 </section>