doc/languages-frameworks/qt.section.md

   1 # Qt {#sec-language-qt}
   2
   3 Writing Nix expressions for Qt libraries and applications is largely similar as for other C++ software.
   4 This section assumes some knowledge of the latter.
   5 There are two problems that the Nixpkgs Qt infrastructure addresses,
   6 which are not shared by other C++ software:
   7
   8 1.  There are usually multiple supported versions of Qt in Nixpkgs.
   9     All of a package's dependencies must be built with the same version of Qt.
  10     This is similar to the version constraints imposed on interpreted languages like Python.
  11 2.  Qt makes extensive use of runtime dependency detection.
  12     Runtime dependencies are made into build dependencies through wrappers.
  13
  14 ## Nix expression for a Qt package (default.nix) {#qt-default-nix}
  15
  16 ```{=docbook}
  17 <programlisting>
  18 { stdenv, lib, qtbase, wrapQtAppsHook }: <co xml:id='qt-default-nix-co-1' />
  19
  20 stdenv.mkDerivation {
  21   pname = "myapp";
  22   version = "1.0";
  23
  24   buildInputs = [ qtbase ];
  25   nativeBuildInputs = [ wrapQtAppsHook ]; <co xml:id='qt-default-nix-co-2' />
  26 }
  27 </programlisting>
  28
  29  <calloutlist>
  30   <callout arearefs='qt-default-nix-co-1'>
  31    <para>
  32     Import Qt modules directly, that is: <literal>qtbase</literal>, <literal>qtdeclarative</literal>, etc.
  33     <emphasis>Do not</emphasis> import Qt package sets such as <literal>qt5</literal>
  34     because the Qt versions of dependencies may not be coherent, causing build and runtime failures.
  35    </para>
  36   </callout>
  37   <callout arearefs='qt-default-nix-co-2'>
  38     <para>
  39       All Qt packages must include <literal>wrapQtAppsHook</literal> in
  40       <literal>nativeBuildInputs</literal>, or you must explicitly set
  41       <literal>dontWrapQtApps</literal>.
  42     </para>
  43   </callout>
  44  </calloutlist>
  45 ```
  46
  47 ## Locating runtime dependencies {#qt-runtime-dependencies}
  48
  49 Qt applications must be wrapped to find runtime dependencies.
  50 Include `wrapQtAppsHook` in `nativeBuildInputs`:
  51
  52 ```nix
  53 { stdenv, wrapQtAppsHook }:
  54
  55 stdenv.mkDerivation {
  56   # ...
  57   nativeBuildInputs = [ wrapQtAppsHook ];
  58 }
  59 ```
  60
  61 Add entries to `qtWrapperArgs` are to modify the wrappers created by
  62 `wrapQtAppsHook`:
  63
  64 ```nix
  65 { stdenv, wrapQtAppsHook }:
  66
  67 stdenv.mkDerivation {
  68   # ...
  69   nativeBuildInputs = [ wrapQtAppsHook ];
  70   qtWrapperArgs = [ ''--prefix PATH : /path/to/bin'' ];
  71 }
  72 ```
  73
  74 The entries are passed as arguments to [wrapProgram](#fun-wrapProgram).
  75
  76 Set `dontWrapQtApps` to stop applications from being wrapped automatically.
  77 Wrap programs manually with `wrapQtApp`, using the syntax of
  78 [wrapProgram](#fun-wrapProgram):
  79
  80 ```nix
  81 { stdenv, lib, wrapQtAppsHook }:
  82
  83 stdenv.mkDerivation {
  84   # ...
  85   nativeBuildInputs = [ wrapQtAppsHook ];
  86   dontWrapQtApps = true;
  87   preFixup = ''
  88       wrapQtApp "$out/bin/myapp" --prefix PATH : /path/to/bin
  89   '';
  90 }
  91 ```
  92
  93 ::: {.note}
  94 `wrapQtAppsHook` ignores files that are non-ELF executables.
  95 This means that scripts won't be automatically wrapped so you'll need to manually wrap them as previously mentioned.
  96 An example of when you'd always need to do this is with Python applications that use PyQt.
  97 :::
  98
  99 ## Adding a library to Nixpkgs {#adding-a-library-to-nixpkgs}
 100
 101 Add Qt libraries to `qt5-packages.nix` to make them available for every
 102 supported Qt version.
 103
 104 ### Example adding a Qt library {#qt-library-all-packages-nix}
 105
 106 The following represents the contents of `qt5-packages.nix`.
 107
 108 ```nix
 109 {
 110   # ...
 111
 112   mylib = callPackage ../path/to/mylib {};
 113
 114   # ...
 115 }
 116 ```
 117
 118 Libraries are built with every available version of Qt.
 119 Use the `meta.broken` attribute to disable the package for unsupported Qt versions:
 120
 121 ```nix
 122 { stdenv, lib, qtbase }:
 123
 124 stdenv.mkDerivation {
 125   # ...
 126   # Disable this library with Qt < 5.9.0
 127   meta.broken = lib.versionOlder qtbase.version "5.9.0";
 128 }
 129 ```
 130
 131 ## Adding an application to Nixpkgs {#adding-an-application-to-nixpkgs}
 132
 133 Add Qt applications to `qt5-packages.nix`. Add an alias to `all-packages.nix`
 134 to select the Qt 5 version used for the application.
 135
 136 ### Example adding a Qt application {#qt-application-all-packages-nix}
 137
 138 The following represents the contents of `qt5-packages.nix`.
 139
 140 ```nix
 141 {
 142   # ...
 143
 144   myapp = callPackage ../path/to/myapp {};
 145
 146   # ...
 147 }
 148 ```
 149
 150 The following represents the contents of `all-packages.nix`.
 151
 152 ```nix
 153 {
 154   # ...
 155
 156   myapp = libsForQt5.myapp;
 157
 158   # ...
 159 }
 160 ```