Merge remote-tracking branch 'NixOS/master' into staging

 <xi:include href="functions/fhs-environments.xml" />

 <xi:include href="functions/shell.xml" />

 <xi:include href="functions/dockertools.xml" />

 <xi:include href="functions/appimagetools.xml" />

 <xi:include href="functions/prefer-remote-fetch.xml" />

 <xi:include href="functions/nix-gitignore.xml" />

</chapter>

<section xmlns="http://docbook.org/ns/docbook"

         xmlns:xlink="http://www.w3.org/1999/xlink"

         xmlns:xi="http://www.w3.org/2001/XInclude"

         xml:id="sec-pkgs-appimageTools">

 <title>pkgs.appimageTools</title>

 <para>

   <varname>pkgs.appimageTools</varname> is a set of functions for extracting and wrapping

   <link xlink:href="https://appimage.org/">AppImage</link> files.

   They are meant to be used if traditional packaging from source is infeasible, or it would take too long.

   To quickly run an AppImage file, <literal>pkgs.appimage-run</literal> can be used as well.

 </para>

 <warning>

  <para>

   The <varname>appimageTools</varname> API is unstable and may be subject to

   backwards-incompatible changes in the future.

  </para>

 </warning>

 <section xml:id="ssec-pkgs-appimageTools-formats">

  <title>AppImage formats</title>

  <para>

   There are different formats for AppImages, see

   <link xlink:href="https://github.com/AppImage/AppImageSpec/blob/74ad9ca2f94bf864a4a0dac1f369dd4f00bd1c28/draft.md#image-format">the specification</link> for details.

  </para>

  <itemizedlist>

   <listitem>

    <para>

     Type 1 images are ISO 9660 files that are also ELF executables.

    </para>

   </listitem>

   <listitem>

    <para>

     Type 2 images are ELF executables with an appended filesystem.

    </para>

   </listitem>

  </itemizedlist>

  <para>

   They can be told apart with <command>file -k</command>:

  </para>

  <screen>

<prompt>$ </prompt>file -k type1.AppImage

type1.AppImage: ELF 64-bit LSB executable, x86-64, version 1 (SYSV) ISO 9660 CD-ROM filesystem data 'AppImage' (Lepton 3.x), scale 0-0,

spot sensor temperature 0.000000, unit celsius, color scheme 0, calibration: offset 0.000000, slope 0.000000, dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2, for GNU/Linux 2.6.18, BuildID[sha1]=d629f6099d2344ad82818172add1d38c5e11bc6d, stripped\012- data

<prompt>$ </prompt>file -k type2.AppImage

type2.AppImage: ELF 64-bit LSB executable, x86-64, version 1 (SYSV) (Lepton 3.x), scale 232-60668, spot sensor temperature -4.187500, color scheme 15, show scale bar, calibration: offset -0.000000, slope 0.000000 (Lepton 2.x), scale 4111-45000, spot sensor temperature 412442.250000, color scheme 3, minimum point enabled, calibration: offset -75402534979642766821519867692934234112.000000, slope 5815371847733706829839455140374904832.000000, dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2, for GNU/Linux 2.6.18, BuildID[sha1]=79dcc4e55a61c293c5e19edbd8d65b202842579f, stripped\012- data

  </screen>

  <para>

   Note how the type 1 AppImage is described as an <literal>ISO 9660 CD-ROM filesystem</literal>, and the type 2 AppImage is not.

  </para>

 </section>

 <section xml:id="ssec-pkgs-appimageTools-wrapping">

  <title>Wrapping</title>

  <para>

    Depending on the type of AppImage you're wrapping, you'll have to use

    <varname>wrapType1</varname> or <varname>wrapType2</varname>.

  </para>

  <programlisting>

appimageTools.wrapType2 { # or wrapType1

  name = "patchwork"; <co xml:id='ex-appimageTools-wrapping-1' />

  src = fetchurl { <co xml:id='ex-appimageTools-wrapping-2' />

    url = https://github.com/ssbc/patchwork/releases/download/v3.11.4/Patchwork-3.11.4-linux-x86_64.AppImage;

    sha256 =  "1blsprpkvm0ws9b96gb36f0rbf8f5jgmw4x6dsb1kswr4ysf591s";

  };

  extraPkgs = pkgs: with pkgs; [ ]; <co xml:id='ex-appimageTools-wrapping-3' />

}</programlisting>

  <calloutlist>

   <callout arearefs='ex-appimageTools-wrapping-1'>

    <para>

     <varname>name</varname> specifies the name of the resulting image.

    </para>

   </callout>

   <callout arearefs='ex-appimageTools-wrapping-2'>

    <para>

     <varname>src</varname> specifies the AppImage file to extract.

    </para>

   </callout>

   <callout arearefs='ex-appimageTools-wrapping-2'>

    <para>

      <varname>extraPkgs</varname> allows you to pass a function to include additional packages

      inside the FHS environment your AppImage is going to run in.

      There are a few ways to learn which dependencies an application needs:

      <itemizedlist>

       <listitem>

        <para>

         Looking through the extracted AppImage files, reading its scripts and running <command>patchelf</command> and <command>ldd</command> on its executables.

         This can also be done in <command>appimage-run</command>, by setting <command>APPIMAGE_DEBUG_EXEC=bash</command>.

        </para>

       </listitem>

       <listitem>

        <para>

         Running <command>strace -vfefile</command> on the wrapped executable, looking for libraries that can't be found.

        </para>

       </listitem>

      </itemizedlist>

    </para>

   </callout>

  </calloutlist>

 </section>

</section>

      mkFixStrictness mkOrder mkBefore mkAfter mkAliasDefinitions

      mkAliasAndWrapDefinitions fixMergeModules mkRemovedOptionModule

      mkRenamedOptionModule mkMergedOptionModule mkChangedOptionModule

      mkAliasOptionModule mkAliasOptionModuleWithPriority doRename filterModules;

      mkAliasOptionModule doRename filterModules;

    inherit (options) isOption mkEnableOption mkSinkUndeclaredOptions

      mergeDefaultOption mergeOneOption mergeEqualOption getValues

      getFiles optionAttrSetToDocList optionAttrSetToDocList'

    fullName = "OpenSSL License";

  };

  osl2 = spdx {

    spdxId = "OSL-2.0";

    fullName = "Open Software License 2.0";

  };

  osl21 = spdx {

    spdxId = "OSL-2.1";

    fullName = "Open Software License 2.1";

     forwards any definitions of boot.copyKernels to

     boot.loader.grub.copyKernels while printing a warning.

     This also copies over the priority from the aliased option to the

     non-aliased option.

  */

  mkRenamedOptionModule = from: to: doRename {

    inherit from to;

    use = id;

  };

  /* Like ‘mkAliasOptionModule’, but copy over the priority of the option as well. */

  mkAliasOptionModuleWithPriority = from: to: doRename {

    inherit from to;

    visible = true;

    warn = false;

    use = id;

    withPriority = true;

  };

  doRename = { from, to, visible, warn, use, withPriority ? false }:

  doRename = { from, to, visible, warn, use, withPriority ? true }:

    { config, options, ... }:

    let

      fromOpt = getAttrFromPath from options;