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>

 <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>