diff options
Diffstat (limited to 'doc/languages-frameworks/qt.section.md')
-rw-r--r-- | doc/languages-frameworks/qt.section.md | 160 |
1 files changed, 160 insertions, 0 deletions
diff --git a/doc/languages-frameworks/qt.section.md b/doc/languages-frameworks/qt.section.md new file mode 100644 index 00000000000..986deeb0d4b --- /dev/null +++ b/doc/languages-frameworks/qt.section.md @@ -0,0 +1,160 @@ +# Qt {#sec-language-qt} + +Writing Nix expressions for Qt libraries and applications is largely similar as for other C++ software. +This section assumes some knowledge of the latter. +There are two problems that the Nixpkgs Qt infrastructure addresses, +which are not shared by other C++ software: + +1. There are usually multiple supported versions of Qt in Nixpkgs. + All of a package's dependencies must be built with the same version of Qt. + This is similar to the version constraints imposed on interpreted languages like Python. +2. Qt makes extensive use of runtime dependency detection. + Runtime dependencies are made into build dependencies through wrappers. + +## Nix expression for a Qt package (default.nix) {#qt-default-nix} + +```{=docbook} +<programlisting> +{ stdenv, lib, qtbase, wrapQtAppsHook }: <co xml:id='qt-default-nix-co-1' /> + +stdenv.mkDerivation { + pname = "myapp"; + version = "1.0"; + + buildInputs = [ qtbase ]; + nativeBuildInputs = [ wrapQtAppsHook ]; <co xml:id='qt-default-nix-co-2' /> +} +</programlisting> + + <calloutlist> + <callout arearefs='qt-default-nix-co-1'> + <para> + Import Qt modules directly, that is: <literal>qtbase</literal>, <literal>qtdeclarative</literal>, etc. + <emphasis>Do not</emphasis> import Qt package sets such as <literal>qt5</literal> + because the Qt versions of dependencies may not be coherent, causing build and runtime failures. + </para> + </callout> + <callout arearefs='qt-default-nix-co-2'> + <para> + All Qt packages must include <literal>wrapQtAppsHook</literal> in + <literal>nativeBuildInputs</literal>, or you must explicitly set + <literal>dontWrapQtApps</literal>. + </para> + </callout> + </calloutlist> +``` + +## Locating runtime dependencies {#qt-runtime-dependencies} + +Qt applications must be wrapped to find runtime dependencies. +Include `wrapQtAppsHook` in `nativeBuildInputs`: + +```nix +{ stdenv, wrapQtAppsHook }: + +stdenv.mkDerivation { + # ... + nativeBuildInputs = [ wrapQtAppsHook ]; +} +``` + +Add entries to `qtWrapperArgs` are to modify the wrappers created by +`wrapQtAppsHook`: + +```nix +{ stdenv, wrapQtAppsHook }: + +stdenv.mkDerivation { + # ... + nativeBuildInputs = [ wrapQtAppsHook ]; + qtWrapperArgs = [ ''--prefix PATH : /path/to/bin'' ]; +} +``` + +The entries are passed as arguments to [wrapProgram](#fun-wrapProgram). + +Set `dontWrapQtApps` to stop applications from being wrapped automatically. +Wrap programs manually with `wrapQtApp`, using the syntax of +[wrapProgram](#fun-wrapProgram): + +```nix +{ stdenv, lib, wrapQtAppsHook }: + +stdenv.mkDerivation { + # ... + nativeBuildInputs = [ wrapQtAppsHook ]; + dontWrapQtApps = true; + preFixup = '' + wrapQtApp "$out/bin/myapp" --prefix PATH : /path/to/bin + ''; +} +``` + +::: {.note} +`wrapQtAppsHook` ignores files that are non-ELF executables. +This means that scripts won't be automatically wrapped so you'll need to manually wrap them as previously mentioned. +An example of when you'd always need to do this is with Python applications that use PyQt. +::: + +## Adding a library to Nixpkgs {#adding-a-library-to-nixpkgs} + +Add Qt libraries to `qt5-packages.nix` to make them available for every +supported Qt version. + +### Example adding a Qt library {#qt-library-all-packages-nix} + +The following represents the contents of `qt5-packages.nix`. + +```nix +{ + # ... + + mylib = callPackage ../path/to/mylib {}; + + # ... +} +``` + +Libraries are built with every available version of Qt. +Use the `meta.broken` attribute to disable the package for unsupported Qt versions: + +```nix +{ stdenv, lib, qtbase }: + +stdenv.mkDerivation { + # ... + # Disable this library with Qt < 5.9.0 + meta.broken = lib.versionOlder qtbase.version "5.9.0"; +} +``` + +## Adding an application to Nixpkgs {#adding-an-application-to-nixpkgs} + +Add Qt applications to `qt5-packages.nix`. Add an alias to `all-packages.nix` +to select the Qt 5 version used for the application. + +### Example adding a Qt application {#qt-application-all-packages-nix} + +The following represents the contents of `qt5-packages.nix`. + +```nix +{ + # ... + + myapp = callPackage ../path/to/myapp {}; + + # ... +} +``` + +The following represents the contents of `all-packages.nix`. + +```nix +{ + # ... + + myapp = libsForQt5.myapp; + + # ... +} +``` |