home-manager: add instantiate subcommand

It can be useful to simply instantiate a Home Manager configuration
without actually building it, for example for the purpose of
pre-building it with some custom command.

PR nix-community#1099

doc/man-home-manager.xml

@@ -17,6 +17,10 @@
     build
    </arg>
 
+   <arg choice="plain">
+    instantiate
+   </arg>
+
    <arg choice="plain">
     edit
    </arg>
@@ -163,6 +167,16 @@
       </para>
      </listitem>
     </varlistentry>
+    <varlistentry>
+     <term>
+      <option>instantiate</option>
+     </term>
+     <listitem>
+      <para>
+       Instantiate the configuration and print the resulting derivation.
+      </para>
+     </listitem>
+    </varlistentry>
     <varlistentry>
      <term>
       <option>edit</option>

home-manager/completion.bash

@@ -278,7 +278,7 @@ _home-manager_completions ()
     #--------------------------#
 
     local Subcommands
-    Subcommands=( "help" "edit" "build" "switch" "generations" "remove-generations" "expire-generations" "packages" "news" "uninstall" )
+    Subcommands=( "help" "edit" "build" "instantiate" "switch" "generations" "remove-generations" "expire-generations" "packages" "news" "uninstall" )
 
     # ^ « home-manager »'s subcommands.
 

home-manager/home-manager

@@ -74,6 +74,28 @@ function setHomeManagerNixPath() {
     done
 }
 
+function doInstantiate() {
+    setConfigFile
+    setHomeManagerNixPath
+
+    local extraArgs=("$@")
+
+    for p in "${EXTRA_NIX_PATH[@]}"; do
+        extraArgs=("${extraArgs[@]}" "-I" "$p")
+    done
+
+    if [[ -v VERBOSE ]]; then
+        extraArgs=("${extraArgs[@]}" "--show-trace")
+    fi
+
+    nix-instantiate \
+        "<home-manager/home-manager/home-manager.nix>" \
+        "${extraArgs[@]}" \
+        "${PASSTHROUGH_OPTS[@]}" \
+        --argstr confPath "$HOME_MANAGER_CONFIG" \
+        --argstr confAttr "$HOME_MANAGER_CONFIG_ATTRIBUTE"
+}
+
 function doBuildAttr() {
     setConfigFile
     setHomeManagerNixPath
@@ -441,6 +463,8 @@ function doHelp() {
     echo
     echo "  build        Build configuration into result directory"
     echo
+    echo "  instantiate  Instantiate the configuration and print the resulting derivation"
+    echo
     echo "  switch       Build and activate configuration"
     echo
     echo "  generations  List all home environment generations"
@@ -471,7 +495,7 @@ while [[ $# -gt 0 ]]; do
     opt="$1"
     shift
     case $opt in
-        build|edit|expire-generations|generations|help|news|packages|remove-generations|switch|uninstall)
+        build|instantiate|edit|expire-generations|generations|help|news|packages|remove-generations|switch|uninstall)
             COMMAND="$opt"
             ;;
         -2)
@@ -542,6 +566,9 @@ case $COMMAND in
     build)
         doBuild
         ;;
+    instantiate)
+        doInstantiate
+        ;;
     switch)
         doSwitch
         ;;