nixpkgs-suyu/doc/languages-frameworks/qt.xml

<section xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xml:id="sec-language-qt">
 <title>Qt</title>

 <para>
  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.
 </para>

 <example xml:id='qt-default-nix'>
  <title>Nix expression for a Qt package (<filename>default.nix</filename>)</title>
<programlisting>
{ mkDerivation, lib, qtbase }: <co xml:id='qt-default-nix-co-1' />

mkDerivation { <co xml:id='qt-default-nix-co-2' />
  pname = "myapp";
  version = "1.0";

  buildInputs = [ qtbase ]; <co xml:id='qt-default-nix-co-3' />
}
   </programlisting>
 </example>

 <calloutlist>
  <callout arearefs='qt-default-nix-co-1'>
   <para>
    Import <literal>mkDerivation</literal> and Qt (such as
    <literal>qtbase</literal> modules directly. <emphasis>Do not</emphasis>
    import Qt package sets; the Qt versions of dependencies may not be
    coherent, causing build and runtime failures.
   </para>
  </callout>
  <callout arearefs='qt-default-nix-co-2'>
   <para>
    Use <literal>mkDerivation</literal> instead of
    <literal>stdenv.mkDerivation</literal>. <literal>mkDerivation</literal> is
    a wrapper around <literal>stdenv.mkDerivation</literal> which applies some
    Qt-specific settings. This deriver accepts the same arguments as
    <literal>stdenv.mkDerivation</literal>; refer to
    <xref linkend='chap-stdenv' /> for details.
   </para>
   <para>
    To use another deriver instead of <literal>stdenv.mkDerivation</literal>,
    use <literal>mkDerivationWith</literal>:
<programlisting>
mkDerivationWith myDeriver {
  # ...
}
</programlisting>
    If you cannot use <literal>mkDerivationWith</literal>, please refer to
    <xref linkend='qt-runtime-dependencies' />.
   </para>
  </callout>
  <callout arearefs='qt-default-nix-co-3'>
   <para>
    <literal>mkDerivation</literal> accepts the same arguments as
    <literal>stdenv.mkDerivation</literal>, such as
    <literal>buildInputs</literal>.
   </para>
  </callout>
 </calloutlist>

 <formalpara xml:id='qt-runtime-dependencies'>
  <title>Locating runtime dependencies</title>
  <para>
   Qt applications need to be wrapped to find runtime dependencies. If you
   cannot use <literal>mkDerivation</literal> or
   <literal>mkDerivationWith</literal> above, include
   <literal>wrapQtAppsHook</literal> in <literal>nativeBuildInputs</literal>:
<programlisting>
stdenv.mkDerivation {
  # ...

  nativeBuildInputs = [ wrapQtAppsHook ];
}
</programlisting>
  </para>
 </formalpara>

 <para>
  Entries added to <literal>qtWrapperArgs</literal> are used to modify the
  wrappers created by <literal>wrapQtAppsHook</literal>. The entries are passed
  as arguments to <xref linkend='fun-wrapProgram' />.
<programlisting>
mkDerivation {
  # ...

  qtWrapperArgs = [ ''--prefix PATH : /path/to/bin'' ];
}
</programlisting>
 </para>

 <para>
  Set <literal>dontWrapQtApps</literal> to stop applications from being wrapped
  automatically. It is required to wrap applications manually with
  <literal>wrapQtApp</literal>, using the syntax of
  <xref linkend='fun-wrapProgram' />:
<programlisting>
mkDerivation {
  # ...

  dontWrapQtApps = true;
  preFixup = ''
      wrapQtApp "$out/bin/myapp" --prefix PATH : /path/to/bin
  '';
}
</programlisting>
 </para>

 <note>
  <para>
   <literal>wrapQtAppsHook</literal> 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.
  </para>
 </note>

 <para>
  Libraries are built with every available version of Qt. Use the
  <literal>meta.broken</literal> attribute to disable the package for
  unsupported Qt versions:
<programlisting>
mkDerivation {
  # ...

  # Disable this library with Qt &lt; 5.9.0
  meta.broken = builtins.compareVersions qtbase.version "5.9.0" &lt; 0;
}
</programlisting>
 </para>

 <formalpara>
  <title>Adding a library to Nixpkgs</title>
  <para>
   Add a Qt library to <filename>all-packages.nix</filename> by adding it to
   the collection inside <literal>mkLibsForQt5</literal>. This ensures that the
   library is built with every available version of Qt as needed.
   <example xml:id='qt-library-all-packages-nix'>
    <title>Adding a Qt library to <filename>all-packages.nix</filename></title>
<programlisting>
{
  # ...

  mkLibsForQt5 = self: with self; {
    # ...

    mylib = callPackage ../path/to/mylib {};
  };

  # ...
}
</programlisting>
   </example>
  </para>
 </formalpara>

 <formalpara>
  <title>Adding an application to Nixpkgs</title>
  <para>
   Add a Qt application to <filename>all-packages.nix</filename> using
   <literal>libsForQt5.callPackage</literal> instead of the usual
   <literal>callPackage</literal>. The former ensures that all dependencies are
   built with the same version of Qt.
   <example xml:id='qt-application-all-packages-nix'>
    <title>Adding a Qt application to <filename>all-packages.nix</filename></title>
<programlisting>
{
  # ...

  myapp = libsForQt5.callPackage ../path/to/myapp/ {};

  # ...
}
</programlisting>
   </example>
  </para>
 </formalpara>
</section>