pyrox.dev
1<section xmlns="http://docbook.org/ns/docbook"
2 xmlns:xlink="http://www.w3.org/1999/xlink"
3 xml:id="sec-language-qt">
4 <title>Qt</title>
5
6 <para>
7 Qt is a comprehensive desktop and mobile application development toolkit for
8 C++. Legacy support is available for Qt 3 and Qt 4, but all current
9 development uses Qt 5. The Qt 5 packages in Nixpkgs are updated frequently to
10 take advantage of new features, but older versions are typically retained
11 until their support window ends. The most important consideration in
12 packaging Qt-based software is ensuring that each package and all its
13 dependencies use the same version of Qt 5; this consideration motivates most
14 of the tools described below.
15 </para>
16
17 <section xml:id="ssec-qt-libraries">
18 <title>Packaging Libraries for Nixpkgs</title>
19
20 <para>
21 Whenever possible, libraries that use Qt 5 should be built with each
22 available version. Packages providing libraries should be added to the
23 top-level function <varname>mkLibsForQt5</varname>, which is used to build a
24 set of libraries for every Qt 5 version. A special
25 <varname>callPackage</varname> function is used in this scope to ensure that
26 the entire dependency tree uses the same Qt 5 version. Import dependencies
27 unqualified, i.e., <literal>qtbase</literal> not
28 <literal>qt5.qtbase</literal>. <emphasis>Do not</emphasis> import a package
29 set such as <literal>qt5</literal> or <literal>libsForQt5</literal>.
30 </para>
31
32 <para>
33 If a library does not support a particular version of Qt 5, it is best to
34 mark it as broken by setting its <literal>meta.broken</literal> attribute. A
35 package may be marked broken for certain versions by testing the
36 <literal>qtbase.version</literal> attribute, which will always give the
37 current Qt 5 version.
38 </para>
39 </section>
40
41 <section xml:id="ssec-qt-applications">
42 <title>Packaging Applications for Nixpkgs</title>
43
44 <para>
45 Call your application expression using
46 <literal>libsForQt5.callPackage</literal> instead of
47 <literal>callPackage</literal>. Import dependencies unqualified, i.e.,
48 <literal>qtbase</literal> not <literal>qt5.qtbase</literal>. <emphasis>Do
49 not</emphasis> import a package set such as <literal>qt5</literal> or
50 <literal>libsForQt5</literal>.
51 </para>
52
53 <para>
54 Qt 5 maintains strict backward compatibility, so it is generally best to
55 build an application package against the latest version using the
56 <varname>libsForQt5</varname> library set. In case a package does not build
57 with the latest Qt version, it is possible to pick a set pinned to a
58 particular version, e.g. <varname>libsForQt55</varname> for Qt 5.5, if that
59 is the latest version the package supports. If a package must be pinned to
60 an older Qt version, be sure to file a bug upstream; because Qt is strictly
61 backwards-compatible, any incompatibility is by definition a bug in the
62 application.
63 </para>
64
65 <para>
66 When testing applications in Nixpkgs, it is a common practice to build the
67 package with <literal>nix-build</literal> and run it using the created
68 symbolic link. This will not work with Qt applications, however, because
69 they have many hard runtime requirements that can only be guaranteed if the
70 package is actually installed. To test a Qt application, install it with
71 <literal>nix-env</literal> or run it inside <literal>nix-shell</literal>.
72 </para>
73 </section>
74</section>