doc/gnome: explain double wrapped binaries

1 files changed, 52 insertions, 0 deletions

diff --git a/doc/languages-frameworks/gnome.xml b/doc/languages-frameworks/gnome.xml
index 2bead65ecf1..399e7c396a8 100644
--- a/doc/languages-frameworks/gnome.xml
+++ b/doc/languages-frameworks/gnome.xml
@@ -166,6 +166,58 @@ preFixup = ''
      </para>
     </listitem>
    </varlistentry>
+   <varlistentry xml:id="ssec-gnome-common-issues-double-wrapped">
+    <term>
+     When using <package>wrapGAppsHook</package> with special derivers you can end up with double wrapped binaries.
+    </term>
+    <listitem>
+     <para>
+      This is because derivers like <function>python.pkgs.buildPythonApplication</function> or <function>qt5.mkDerivation</function> have setup-hooks automatically added that produce wrappers with <package>makeWrapper</package>. The simplest way to workaround that is to disable the <package>wrapGAppsHook</package> automatic wrapping with <code>dontWrapGApps = true;</code> and pass the arguments it intended to pass to <package>makeWrapper</package> to another.
+     </para>
+     <para>
+      In the case of a Python application it could look like:
+<programlisting>
+python3.pkgs.buildPythonApplication {
+  pname = "gnome-music";
+  version = "3.32.2";
+
+  nativeBuildInputs = [
+    wrapGAppsHook
+    gobject-introspection
+    ...
+  ];
+
+  dontWrapGApps = true;
+
+  # Arguments to be passed to `makeWrapper`, only used by buildPython*
+  makeWrapperArgs = [
+    "\${gappsWrapperArgs[@]}"
+  ];
+}
+</programlisting>
+      And for a QT app like:
+<programlisting>
+mkDerivation {
+  pname = "calibre";
+  version = "3.47.0";
+
+  nativeBuildInputs = [
+    wrapGAppsHook
+    qmake
+    ...
+  ];
+
+  dontWrapGApps = true;
+
+  # Arguments to be passed to `makeWrapper`, only used by qt5’s mkDerivation
+  qtWrapperArgs [
+    "\${gappsWrapperArgs[@]}"
+  ];
+}
+</programlisting>
+     </para>
+    </listitem>
+   </varlistentry>
    <varlistentry xml:id="ssec-gnome-common-issues-unwrappable-package">
     <term>
      I am packaging a project that cannot be wrapped, like a library or GNOME Shell extension.