vimUtils.makeCustomizable: rewrite to include more things

The current wrapper only includes vim, gvim and the man pages
(optionally). This rewrite distinguishes two scenarios, which I expect
cover the majority of use cases:

- standalone mode, when `name != "vim"`, means the user already has a
  vim in scope and only wants to add a customized version with a
  different name. In this case we only include wrappers for `/bin/*vim`.
- non-standalone mode, when `name == "vim"`, means the user expects a
  normal vim package that uses the specified configuration. In this case
  we include everything in the original derivation, with wrappers for
  all the executables that accept a vimrc.

4 files changed, 134 insertions, 56 deletions

diff --git a/doc/languages-frameworks/vim.section.md b/doc/languages-frameworks/vim.section.md
index a615d585b151c..04cb271a43be4 100644
--- a/doc/languages-frameworks/vim.section.md
+++ b/doc/languages-frameworks/vim.section.md
@@ -18,7 +18,7 @@ Adding custom .vimrc lines can be done using the following code:
 
 ```nix
 vim_configurable.customize {
-  # `name` specifies the name of the executable and package
+  # `name` optionally specifies the name of the executable and package
   name = "vim-with-plugins";
 
   vimrcConfig.customRC = ''
@@ -28,6 +28,9 @@ vim_configurable.customize {
 ```
 
 This configuration is used when Vim is invoked with the command specified as name, in this case `vim-with-plugins`.
+You can also omit `name` to customize Vim itself. See the
+[definition of `vimUtils.makeCustomizable`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vim/plugins/vim-utils.nix#L408)
+for all supported options.
 
 For Neovim the `configure` argument can be overridden to achieve the same:
 
diff --git a/nixos/doc/manual/from_md/release-notes/rl-2205.section.xml b/nixos/doc/manual/from_md/release-notes/rl-2205.section.xml
index fc7cb28ffdfd3..c128be6423bc4 100644
--- a/nixos/doc/manual/from_md/release-notes/rl-2205.section.xml
+++ b/nixos/doc/manual/from_md/release-notes/rl-2205.section.xml
@@ -796,6 +796,54 @@
       </listitem>
       <listitem>
         <para>
+          The <literal>vim.customize</literal> function produced by
+          <literal>vimUtils.makeCustomizable</literal> now has a
+          slightly different interface:
+        </para>
+        <itemizedlist spacing="compact">
+          <listitem>
+            <para>
+              The wrapper now includes everything in the given Vim
+              derivation if <literal>name</literal> is
+              <literal>&quot;vim&quot;</literal> (the default). This
+              makes the <literal>wrapManual</literal> argument obsolete,
+              but this behavior can be overriden by setting the
+              <literal>standalone</literal> argument.
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              All the executables present in the given derivation (or,
+              in <literal>standalone</literal> mode, only the
+              <literal>*vim</literal> ones) are wrapped. This makes the
+              <literal>wrapGui</literal> argument obsolete.
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              The <literal>vimExecutableName</literal> and
+              <literal>gvimExecutableName</literal> arguments were
+              replaced by a single <literal>executableName</literal>
+              argument in which the shell variable
+              <literal>$exe</literal> can be used to refer to the
+              wrapped executable’s name.
+            </para>
+          </listitem>
+        </itemizedlist>
+        <para>
+          See the comments in
+          <literal>pkgs/applications/editors/vim/plugins/vim-utils.nix</literal>
+          for more details.
+        </para>
+        <para>
+          <literal>vimUtils.vimWithRC</literal> was removed. You should
+          instead use <literal>customize</literal> on a Vim derivation,
+          which now accepts <literal>vimrcFile</literal> and
+          <literal>gvimrcFile</literal> arguments.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
           <literal>tilp2</literal> was removed together with its module
         </para>
       </listitem>
diff --git a/nixos/doc/manual/release-notes/rl-2205.section.md b/nixos/doc/manual/release-notes/rl-2205.section.md
index 2ff5865b73554..b00a4781c4caf 100644
--- a/nixos/doc/manual/release-notes/rl-2205.section.md
+++ b/nixos/doc/manual/release-notes/rl-2205.section.md
@@ -315,6 +315,15 @@ In addition to numerous new and upgraded packages, this release has the followin
 
 - `pkgs._7zz` is now correctly licensed as LGPL3+ and BSD3 with optional unfree unRAR licensed code
 
+- The `vim.customize` function produced by `vimUtils.makeCustomizable` now has a slightly different interface:
+  * The wrapper now includes everything in the given Vim derivation if `name` is `"vim"` (the default). This makes the `wrapManual` argument obsolete, but this behavior can be overriden by setting the `standalone` argument.
+  * All the executables present in the given derivation (or, in `standalone` mode, only the `*vim` ones) are wrapped. This makes the `wrapGui` argument obsolete.
+  * The `vimExecutableName` and `gvimExecutableName` arguments were replaced by a single `executableName` argument in which the shell variable `$exe` can be used to refer to the wrapped executable's name.
+
+  See the comments in `pkgs/applications/editors/vim/plugins/vim-utils.nix` for more details.
+
+  `vimUtils.vimWithRC` was removed. You should instead use `customize` on a Vim derivation, which now accepts `vimrcFile` and `gvimrcFile` arguments.
+
 - `tilp2` was removed together with its module
 
 - The F-PROT antivirus (`fprot` package) and its service module were removed because it
diff --git a/pkgs/applications/editors/vim/plugins/vim-utils.nix b/pkgs/applications/editors/vim/plugins/vim-utils.nix
index 4183b6214351a..b291928f25aaf 100644
--- a/pkgs/applications/editors/vim/plugins/vim-utils.nix
+++ b/pkgs/applications/editors/vim/plugins/vim-utils.nix
@@ -1,5 +1,6 @@
 # tests available at pkgs/test/vim
-{ lib, stdenv, vim, vimPlugins, vim_configurable, buildEnv, writeText, writeScriptBin
+{ lib, stdenv, vim, vimPlugins, vim_configurable, buildEnv, writeText
+, runCommand, makeWrapper
 , nix-prefetch-hg, nix-prefetch-git
 , fetchFromGitHub, runtimeShell
 , hasLuaModule
@@ -16,7 +17,7 @@ Install Vim like this eg using nixos option environment.systemPackages which wil
 vim-with-plugins in PATH:
 
   vim_configurable.customize {
-    name = "vim-with-plugins";
+    name = "vim-with-plugins"; # optional
 
     # add custom .vimrc lines like this:
     vimrcConfig.customRC = ''
@@ -404,64 +405,81 @@ rec {
   inherit vimrcContent;
   inherit packDir;
 
-  # shell script with custom name passing [-u vimrc] [-U gvimrc] to vim
-  vimWithRC = {
-    vimExecutable,
-    gvimExecutable,
-    vimManPages,
-    wrapManual,
-    wrapGui,
-    name ? "vim",
-    vimrcFile ? null,
-    gvimrcFile ? null,
-    vimExecutableName,
-    gvimExecutableName,
-  }:
-    let
-      rcOption = o: file: lib.optionalString (file != null) "-${o} ${file}";
-      vimWrapperScript = writeScriptBin vimExecutableName ''
-        #!${runtimeShell}
-        exec ${vimExecutable} ${rcOption "u" vimrcFile} ${rcOption "U" gvimrcFile} "$@"
-      '';
-      gvimWrapperScript = writeScriptBin gvimExecutableName ''
-        #!${stdenv.shell}
-        exec ${gvimExecutable} ${rcOption "u" vimrcFile} ${rcOption "U" gvimrcFile} "$@"
-      '';
-    in
-      buildEnv {
-        inherit name;
-        paths = [
-          vimWrapperScript
-        ] ++ lib.optional wrapGui gvimWrapperScript
-          ++ lib.optional wrapManual vimManPages
-        ;
-      };
-
-  # add a customize option to a vim derivation
-  makeCustomizable = vim: vim // {
-    customize = {
-      name,
-      vimrcConfig,
-      wrapManual ? true,
-      wrapGui ? false,
-      vimExecutableName ? name,
-      gvimExecutableName ? (lib.concatStrings [ "g" name ]),
-    }: vimWithRC {
-      vimExecutable = "${vim}/bin/vim";
-      gvimExecutable = "${vim}/bin/gvim";
-      inherit name wrapManual wrapGui vimExecutableName gvimExecutableName;
-      vimrcFile = vimrcFile vimrcConfig;
-      vimManPages = buildEnv {
-        name = "vim-doc";
-        paths = [ vim ];
-        pathsToLink = [ "/share/man" ];
-      };
-    };
+  makeCustomizable = let
+    mkVimrcFile = vimrcFile; # avoid conflict with argument name
+  in vim: vim // {
+    # Returns a customized vim that uses the specified vimrc configuration.
+    customize =
+      { # The name of the derivation.
+        name ? "vim"
+      , # A shell word used to specify the names of the customized executables.
+        # The shell variable $exe can be used to refer to the wrapped executable's name.
+        # Examples: "my-$exe", "$exe-with-plugins", "\${exe/vim/v1m}"
+        executableName ?
+          if lib.hasInfix "vim" name then
+            lib.replaceStrings [ "vim" ] [ "$exe" ] name
+          else
+            "\${exe/vim/${lib.escapeShellArg name}}"
+      , # A custom vimrc configuration, treated as an argument to vimrcContent (see the documentation in this file).
+        vimrcConfig ? null
+      , # A custom vimrc file.
+        vimrcFile ? null
+      , # A custom gvimrc file.
+        gvimrcFile ? null
+      , # If set to true, return the *vim wrappers only.
+        # If set to false, overlay the wrappers on top of the original vim derivation.
+        # This ensures that things like man pages and .desktop files are available.
+        standalone ? name != "vim" && wrapManual != true
+
+      , # deprecated arguments (TODO: remove eventually)
+        wrapManual ? null, wrapGui ? null, vimExecutableName ? null, gvimExecutableName ? null,
+      }:
+      lib.warnIf (wrapManual != null) ''
+        vim.customize: wrapManual is deprecated: the manual is now included by default if `name == "vim"`.
+        ${if wrapManual == true && name != "vim" then "Set `standalone = false` to include the manual."
+        else if wrapManual == false && name == "vim" then "Set `standalone = true` to get the *vim wrappers only."
+        else ""}''
+      lib.warnIf (wrapGui != null)
+        "vim.customize: wrapGui is deprecated: gvim is now automatically included if present"
+      lib.throwIfNot (vimExecutableName == null && gvimExecutableName == null)
+        "vim.customize: (g)vimExecutableName is deprecated: use executableName instead (see source code for examples)"
+      (let
+        vimrc =
+          if vimrcFile != null then vimrcFile
+          else if vimrcConfig != null then mkVimrcFile vimrcConfig
+          else throw "at least one of vimrcConfig and vimrcFile must be specified";
+        bin = runCommand "${name}-bin" { buildInputs = [ makeWrapper ]; } ''
+          vimrc=${lib.escapeShellArg vimrc}
+          gvimrc=${if gvimrcFile != null then lib.escapeShellArg gvimrcFile else ""}
+
+          mkdir -p "$out/bin"
+          for exe in ${
+            if standalone then "{,g,r,rg,e}vim {,g}vimdiff"
+            else "{,g,r,rg,e}{vim,view} {,g}vimdiff ex"
+          }; do
+            if [[ -e ${vim}/bin/$exe ]]; then
+              dest="$out/bin/${executableName}"
+              if [[ -e $dest ]]; then
+                echo "ambiguous executableName: ''${dest##*/} already exists"
+                continue
+              fi
+              makeWrapper ${vim}/bin/"$exe" "$dest" \
+                --add-flags "-u ''${vimrc@Q} ''${gvimrc:+-U ''${gvimrc@Q}}"
+            fi
+          done
+        '';
+      in if standalone then bin else
+        buildEnv {
+          inherit name;
+          paths = [ (lib.lowPrio vim) bin ];
+        });
 
     override = f: makeCustomizable (vim.override f);
     overrideAttrs = f: makeCustomizable (vim.overrideAttrs f);
   };
 
+  vimWithRC = throw "vimWithRC was removed, please use vim.customize instead";
+
   pluginnames2Nix = {name, namefiles} : vim_configurable.customize {
     inherit name;
     vimrcConfig.vam.knownPlugins = vimPlugins;