Merge master into staging-next

 <section xml:id="function-library-lib.attrsets.zipAttrs">

  <title><function>lib.attrsets.zipAttrs</function></title>

  <subtitle><literal>zipAttrsWith :: [ AttrSet ] -> AttrSet</literal>

  <subtitle><literal>zipAttrs :: [ AttrSet ] -> AttrSet</literal>

  </subtitle>

  <xi:include href="./locations.xml" xpointer="lib.attrsets.zipAttrs" />

- It uses the `fetchFromGitHub` fetcher to get its source.

- `useDune2 = true` ensures that the latest version of Dune is used for the

  build (this may become the default value in a future release).

- `useDune2 = true` ensures that Dune version 2 is used for the

  build (this is the default; set to `false` to use Dune version 1).

- It sets the optional `doCheck` attribute such that tests will be run with

  `dune runtest -p angstrom` after the build (`dune build -p angstrom`) is

`systemd.timers` (the list of commands to be executed periodically by

`systemd`).

Care must be taken when writing systemd services using `Exec*` directives. By

default systemd performs substitution on `%<char>` specifiers in these

directives, expands environment variables from `$FOO` and `${FOO}`, splits

arguments on whitespace, and splits commands on `;`. All of these must be escaped

to avoid unexpected substitution or splitting when interpolating into an `Exec*`

directive, e.g. when using an `extraArgs` option to pass additional arguments to

the service. The functions `utils.escapeSystemdExecArg` and

`utils.escapeSystemdExecArgs` are provided for this, see [Example: Escaping in

Exec directives](#exec-escaping-example) for an example. When using these

functions system environment substitution should *not* be disabled explicitly.

::: {#locate-example .example}

::: {.title}

**Example: NixOS Module for the "locate" Service**

```

:::

::: {#exec-escaping-example .example}

::: {.title}

**Example: Escaping in Exec directives**

:::

```nix

{ config, lib, pkgs, utils, ... }:

with lib;

let

  cfg = config.services.echo;

  echoAll = pkgs.writeScript "echo-all" ''

    #! ${pkgs.runtimeShell}

    for s in "$@"; do

      printf '%s\n' "$s"

    done

  '';

  args = [ "a%Nything" "lang=\${LANG}" ";" "/bin/sh -c date" ];

in {

  systemd.services.echo =

    { description = "Echo to the journal";

      wantedBy = [ "multi-user.target" ];

      serviceConfig.Type = "oneshot";

      serviceConfig.ExecStart = ''

        ${echoAll} ${utils.escapeSystemdExecArgs args}

      '';

    };

}

```

:::

```{=docbook}

<xi:include href="option-declarations.section.xml" />

<xi:include href="option-types.section.xml" />

    services) and <literal>systemd.timers</literal> (the list of

    commands to be executed periodically by <literal>systemd</literal>).

  </para>

  <para>

    Care must be taken when writing systemd services using

    <literal>Exec*</literal> directives. By default systemd performs

    substitution on <literal>%&lt;char&gt;</literal> specifiers in these

    directives, expands environment variables from

    <literal>$FOO</literal> and <literal>${FOO}</literal>, splits

    arguments on whitespace, and splits commands on

    <literal>;</literal>. All of these must be escaped to avoid

    unexpected substitution or splitting when interpolating into an

    <literal>Exec*</literal> directive, e.g. when using an

    <literal>extraArgs</literal> option to pass additional arguments to

    the service. The functions

    <literal>utils.escapeSystemdExecArg</literal> and

    <literal>utils.escapeSystemdExecArgs</literal> are provided for

    this, see <link linkend="exec-escaping-example">Example: Escaping in

    Exec directives</link> for an example. When using these functions

    system environment substitution should <emphasis>not</emphasis> be

    disabled explicitly.

  </para>

  <anchor xml:id="locate-example" />

  <para>

    <emphasis role="strong">Example: NixOS Module for the

      };

  };

}

</programlisting>

  <anchor xml:id="exec-escaping-example" />

  <para>

    <emphasis role="strong">Example: Escaping in Exec

    directives</emphasis>

  </para>

  <programlisting language="bash">

{ config, lib, pkgs, utils, ... }:

with lib;

let

  cfg = config.services.echo;

  echoAll = pkgs.writeScript "echo-all" ''

    #! ${pkgs.runtimeShell}

    for s in "$@"; do

      printf '%s\n' "$s"

    done

  '';

  args = [ "a%Nything" "lang=\${LANG}" ";" "/bin/sh -c date" ];

in {

  systemd.services.echo =

    { description = "Echo to the journal";

      wantedBy = [ "multi-user.target" ];

      serviceConfig.Type = "oneshot";

      serviceConfig.ExecStart = ''

        ${echoAll} ${utils.escapeSystemdExecArgs args}

      '';

    };

}

</programlisting>

  <xi:include href="option-declarations.section.xml" />

  <xi:include href="option-types.section.xml" />

   replaceChars ["/" "-" " "] ["-" "\\x2d" "\\x20"]

   (removePrefix "/" s);

  # Quotes an argument for use in Exec* service lines.

  # systemd accepts "-quoted strings with escape sequences, toJSON produces

  # a subset of these.

  # Additionally we escape % to disallow expansion of % specifiers. Any lone ;

  # in the input will be turned it ";" and thus lose its special meaning.

  # Every $ is escaped to $$, this makes it unnecessary to disable environment

  # substitution for the directive.

  escapeSystemdExecArg = arg:

    let

      s = if builtins.isPath arg then "${arg}"

        else if builtins.isString arg then arg

        else if builtins.isInt arg || builtins.isFloat arg then toString arg

        else throw "escapeSystemdExecArg only allows strings, paths and numbers";

    in

      replaceChars [ "%" "$" ] [ "%%" "$$" ] (builtins.toJSON s);

  # Quotes a list of arguments into a single string for use in a Exec*

  # line.

  escapeSystemdExecArgs = concatMapStringsSep " " escapeSystemdExecArg;

  # Returns a system path for a given shell package

  toShellPath = shell:

    if types.shellPackage.check shell then