From b6bca3d80619f1565ba0ea635b0d38234e41c6bd Mon Sep 17 00:00:00 2001 From: Wil Taylor Date: Mon, 30 Nov 2020 14:30:29 +1000 Subject: doc/Qt: migrate to CommonMark (#105004) * Updated QT section * Fixed trailing whitespace * Update doc/languages-frameworks/qt.section.md Co-authored-by: Jan Tojnar * Update doc/languages-frameworks/qt.section.md Co-authored-by: Jan Tojnar * Made changes to docs as per jtojnar's review * Added docbook tags for callouts back in Co-authored-by: Jan Tojnar --- doc/languages-frameworks/index.xml | 2 +- doc/languages-frameworks/qt.section.md | 124 +++++++++++++++++++++++++++ doc/languages-frameworks/qt.xml | 149 --------------------------------- 3 files changed, 125 insertions(+), 150 deletions(-) create mode 100644 doc/languages-frameworks/qt.section.md delete mode 100644 doc/languages-frameworks/qt.xml (limited to 'doc/languages-frameworks') diff --git a/doc/languages-frameworks/index.xml b/doc/languages-frameworks/index.xml index 7a4c54fca8d0..22bc6e1baaaf 100644 --- a/doc/languages-frameworks/index.xml +++ b/doc/languages-frameworks/index.xml @@ -25,7 +25,7 @@ - + diff --git a/doc/languages-frameworks/qt.section.md b/doc/languages-frameworks/qt.section.md new file mode 100644 index 000000000000..4a37eb4ef7db --- /dev/null +++ b/doc/languages-frameworks/qt.section.md @@ -0,0 +1,124 @@ +# Qt {#sec-language-qt} + +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. + +## Nix expression for a Qt package (default.nix) {#qt-default-nix} + +```{=docbook} + +{ mkDerivation, lib, qtbase }: + +mkDerivation { + pname = "myapp"; + version = "1.0"; + + buildInputs = [ qtbase ]; +} + + + + + + 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. + + + +``` + +## Locating runtime dependencies {#qt-runtime-dependencies} +Qt applications need to be wrapped to find runtime dependencies. If you cannot use `mkDerivation` or `mkDerivationWith` above, include `wrapQtAppsHook` in `nativeBuildInputs`: + +```nix +stdenv.mkDerivation { + # ... + + nativeBuildInputs = [ wrapQtAppsHook ]; +} +``` +Entries added to `qtWrapperArgs` are used to modify the wrappers created by `wrapQtAppsHook`. The entries are passed as arguments to [wrapProgram executable makeWrapperArgs](#fun-wrapProgram). + +```nix +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 [wrapProgram executable makeWrapperArgs](#fun-wrapProgram): + +```nix +mkDerivation { + # ... + + 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. + +Libraries are built with every available version of Qt. Use the `meta.broken` attribute to disable the package for unsupported Qt versions: + +```nix +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. + +### Example Adding a Qt library to all-packages.nix {#qt-library-all-packages-nix} + +``` +{ + # ... + + 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. + +### Example Adding a QT application to all-packages.nix {#qt-application-all-packages-nix} +```nix +{ + # ... + + myapp = libsForQt5.callPackage ../path/to/myapp/ {}; + + # ... +} +``` diff --git a/doc/languages-frameworks/qt.xml b/doc/languages-frameworks/qt.xml deleted file mode 100644 index ec95621d8ff2..000000000000 --- a/doc/languages-frameworks/qt.xml +++ /dev/null @@ -1,149 +0,0 @@ -
- Qt - - - 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. - - - - Nix expression for a Qt package (<filename>default.nix</filename>) - -{ mkDerivation, lib, qtbase }: - -mkDerivation { - pname = "myapp"; - version = "1.0"; - - buildInputs = [ qtbase ]; -} - - - - - - - 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. - - - - - - 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 { - # ... - - 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 - ''; -} - - - - - - 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. - - - - - 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/ {}; - - # ... -} - - - - -
-- cgit v1.2.3