treewide: deprecate `DRY_RUN_CMD` and `DRY_RUN_NULL`

As a replacement, this adds the `run` helper function.

docs/release-notes/rl-2405.md

@@ -31,6 +31,35 @@ This release has the following notable changes:
   _all_ Home Manager state from your user environment. This includes
   removing all your historic Home Manager generations!
 
+- The use of `$DRY_RUN_CMD` and `$DRY_RUN_NULL` in activation script
+  blocks is now deprecated. Instead use the new shell function
+  {command}`run`. In most cases it is sufficient to replace
+  `$DRY_RUN_CMD` by {command}`run`. For example, if your configuration
+  currently contains
+
+  ```nix
+  home.activation.reportChanges = config.lib.dag.entryAnywhere ''
+    if [[ -v oldGenPath ]]; then
+      $DRY_RUN_CMD nix store diff-closures $oldGenPath $newGenPath
+    fi
+  '';
+  ```
+
+  then you are now encouraged to change to
+
+  ```nix
+  home.activation.reportChanges = config.lib.dag.entryAnywhere ''
+    if [[ -v oldGenPath ]]; then
+      run nix store diff-closures $oldGenPath $newGenPath
+    fi
+  '';
+  ```
+
+  See the description of [home.activation](#opt-home.activation) for
+  more. The deprecated variables will continue to work for now but
+  their use may in the future trigger a warning message and eventually
+  they may be removed entirely.
+
 ## State Version Changes {#sec-release-24.05-state-version-changes}
 
 The state version in this release includes the changes below. These

home-manager/home-manager

@@ -21,18 +21,12 @@ function setNixProfileCommands() {
     fi
 }
 
-function setVerboseAndDryRun() {
+function setVerboseArg() {
     if [[ -v VERBOSE ]]; then
         export VERBOSE_ARG="--verbose"
     else
         export VERBOSE_ARG=""
     fi
-
-    if [[ -v DRY_RUN ]] ; then
-        export DRY_RUN_CMD=echo
-    else
-        export DRY_RUN_CMD=""
-    fi
 }
 
 function setWorkDir() {
@@ -661,7 +655,7 @@ function doListGens() {
 # generations to remove.
 function doRmGenerations() {
     setHomeManagerPathVariables
-    setVerboseAndDryRun
+    setVerboseArg
 
     pushd "$HM_PROFILE_DIR" > /dev/null
 
@@ -674,7 +668,7 @@ function doRmGenerations() {
             _i 'Cannot remove the current generation %s' "$generationId" >&2
         else
             _i 'Removing generation %s' "$generationId"
-            $DRY_RUN_CMD rm $VERBOSE_ARG $linkName
+            run rm $VERBOSE_ARG $linkName
         fi
     done
 
@@ -809,7 +803,6 @@ function doShowNews() {
 
 function doUninstall() {
     setHomeManagerPathVariables
-    setVerboseAndDryRun
     setNixProfileCommands
 
     _i 'This will remove Home Manager from your system.'

lib/bash/home-manager.sh

@@ -83,3 +83,27 @@ function _iNote() {
     _i "$@"
     echo -n "${normalColor}"
 }
+
+# Runs the given command on live run, otherwise prints the command to standard
+# output.
+#
+# If given the command line option `--silence`, then the command's standard and
+# error output is sent to `/dev/null` on a live run.
+#
+# Note, the run function is exported. I.e., it is available also to called Bash
+# script.
+function run() {
+    if [[ $1 == '--silence' ]]; then
+        local silence=1
+        shift
+    fi
+
+    if [[ -v DRY_RUN ]] ; then
+        echo "$@"
+    elif [[ -v silence ]] ; then
+        "$@" > /dev/null 2>&1
+    else
+        "$@"
+    fi
+}
+export -f run

modules/files.nix

@@ -169,6 +169,8 @@ in
     home.activation.linkGeneration = hm.dag.entryAfter ["writeBoundary"] (
       let
         link = pkgs.writeShellScript "link" ''
+          ${config.lib.bash.initHomeManagerLib}
+
           newGenFiles="$1"
           shift
           for sourcePath in "$@" ; do
@@ -177,7 +179,7 @@ in
             if [[ -e "$targetPath" && ! -L "$targetPath" && -n "$HOME_MANAGER_BACKUP_EXT" ]] ; then
               # The target exists, back it up
               backup="$targetPath.$HOME_MANAGER_BACKUP_EXT"
-              $DRY_RUN_CMD mv $VERBOSE_ARG "$targetPath" "$backup" || errorEcho "Moving '$targetPath' failed!"
+              run mv $VERBOSE_ARG "$targetPath" "$backup" || errorEcho "Moving '$targetPath' failed!"
             fi
 
             if [[ -e "$targetPath" && ! -L "$targetPath" ]] && cmp -s "$sourcePath" "$targetPath" ; then
@@ -186,8 +188,8 @@ in
             else
               # Place that symlink, --force
               # This can still fail if the target is a directory, in which case we bail out.
-              $DRY_RUN_CMD mkdir -p $VERBOSE_ARG "$(dirname "$targetPath")"
+              run mkdir -p $VERBOSE_ARG "$(dirname "$targetPath")"
-              $DRY_RUN_CMD ln -Tsf $VERBOSE_ARG "$sourcePath" "$targetPath" || exit 1
+              run ln -Tsf $VERBOSE_ARG "$sourcePath" "$targetPath" || exit 1
             fi
           done
         '';
@@ -209,7 +211,7 @@ in
               warnEcho "Path '$targetPath' does not link into a Home Manager generation. Skipping delete."
             else
               $VERBOSE_ECHO "Checking $targetPath: gone (deleting)"
-              $DRY_RUN_CMD rm $VERBOSE_ARG "$targetPath"
+              run rm $VERBOSE_ARG "$targetPath"
 
               # Recursively delete empty parent directories.
               targetDir="$(dirname "$relativePath")"
@@ -219,7 +221,7 @@ in
                 # Call rmdir with a relative path excluding $HOME.
                 # Otherwise, it might try to delete $HOME and exit
                 # with a permission error.
-                $DRY_RUN_CMD rmdir $VERBOSE_ARG \
+                run rmdir $VERBOSE_ARG \
                     -p --ignore-fail-on-non-empty \
                     "$targetDir"
 
@@ -267,14 +269,14 @@ in
               nix profile list --profile "$genProfilePath" \
                 | cut -d ' ' -f 4 \
                 | xargs -t $DRY_RUN_CMD nix profile remove $VERBOSE_ARG --profile "$genProfilePath"
-              $DRY_RUN_CMD nix profile install $VERBOSE_ARG --profile "$genProfilePath" "$newGenPath"
+              run nix profile install $VERBOSE_ARG --profile "$genProfilePath" "$newGenPath"
             else
-              $DRY_RUN_CMD nix-env $VERBOSE_ARG --profile "$genProfilePath" --set "$newGenPath"
+              run nix-env $VERBOSE_ARG --profile "$genProfilePath" --set "$newGenPath"
             fi
 
-            $DRY_RUN_CMD nix-store --realise "$newGenPath" --add-root "$newGenGcPath" > "$DRY_RUN_NULL"
+            run --silence nix-store --realise "$newGenPath" --add-root "$newGenGcPath"
             if [[ -e "$legacyGenGcPath" ]]; then
-              $DRY_RUN_CMD rm $VERBOSE_ARG "$legacyGenGcPath"
+              run rm $VERBOSE_ARG "$legacyGenGcPath"
             fi
           else
             _i "No change so reusing latest profile generation %s" "$oldGenNum"

modules/home-environment.nix

@@ -374,7 +374,7 @@ in
       example = literalExpression ''
         {
           myActivationAction = lib.hm.dag.entryAfter ["writeBoundary"] '''
-            $DRY_RUN_CMD ln -s $VERBOSE_ARG \
+            run ln -s $VERBOSE_ARG \
                 ''${builtins.toPath ./link-me-directly} $HOME
           ''';
         }
@@ -396,11 +396,19 @@ in
         collisions between non-managed files and files defined in
         [](#opt-home.file).
 
-        A script block should respect the {var}`DRY_RUN`
+        A script block should respect the {var}`DRY_RUN` variable. If it is set
-        variable, if it is set then the actions taken by the script
+        then the actions taken by the script should be logged to standard out
-        should be logged to standard out and not actually performed.
+        and not actually performed. A convenient shell function {command}`run`
-        The variable {var}`DRY_RUN_CMD` is set to
+        is provided for activation script blocks. It is used as follows:
-        {command}`echo` if dry run is enabled.
+
+        {command}`run {command}`
+        : Runs the given command on live run, otherwise prints the command to
+        standard output.
+
+        {command}`run --silence {command}`
+        : Runs the given command on live run and sends its standard and error
+        output to {file}`/dev/null`, otherwise prints the command to standard
+        output.
 
         A script block should also respect the
         {var}`VERBOSE` variable, and if set print
@@ -594,7 +602,7 @@ in
 
             nixProfileRemove 'home-manager-path'
 
-            $DRY_RUN_CMD $oldNix profile install $1
+            run $oldNix profile install $1
           }
 
           if [[ -e ${cfg.profileDirectory}/manifest.json ]] ; then
@@ -604,7 +612,7 @@ in
             REMOVE_CMD_SYNTAX='nix profile remove {number | store path}'
           else
             INSTALL_CMD="nix-env -i"
-            INSTALL_CMD_ACTUAL="$DRY_RUN_CMD nix-env -i"
+            INSTALL_CMD_ACTUAL="run nix-env -i"
             LIST_CMD="nix-env -q"
             REMOVE_CMD_SYNTAX='nix-env -e {package name}'
           fi

modules/launchd/default.nix

@@ -162,7 +162,7 @@ in {
               fi
               if [[ -f "$dstPath" ]]; then
                 for (( i = 0; i < bootout_retries; i++ )); do
-                  $DRY_RUN_CMD /bin/launchctl bootout "$domain/$agentName" || err=$?
+                  run /bin/launchctl bootout "$domain/$agentName" || err=$?
                   if [[ -v DRY_RUN ]]; then
                     break
                   fi
@@ -177,8 +177,8 @@ in {
                   return 1
                 fi
               fi
-              $DRY_RUN_CMD install -Dm444 -T "$srcPath" "$dstPath"
+              run install -Dm444 -T "$srcPath" "$dstPath"
-              $DRY_RUN_CMD /bin/launchctl bootstrap "$domain" "$dstPath"
+              run /bin/launchctl bootstrap "$domain" "$dstPath"
             done
 
             if [[ ! -e "$oldDir" ]]; then
@@ -194,7 +194,7 @@ in {
                 continue
               fi
 
-              $DRY_RUN_CMD /bin/launchctl bootout "$domain/$agentName" || :
+              run /bin/launchctl bootout "$domain/$agentName" || :
               if [[ ! -e "$dstPath" ]]; then
                 continue
               fi
@@ -202,7 +202,7 @@ in {
                 warnEcho "Skipping deletion of '$dstPath', since its contents have diverged"
                 continue
               fi
-              $DRY_RUN_CMD rm -f $VERBOSE_ARG "$dstPath"
+              run rm -f $VERBOSE_ARG "$dstPath"
             done
           }
 

modules/lib-bash/activation-init.sh

@@ -115,7 +115,7 @@ function nixProfileRemove() {
         nixProfileList "$1" | xargs -t $DRY_RUN_CMD nix profile remove $VERBOSE_ARG
     else
         if nix-env -q | grep -q "^$1$"; then
-            $DRY_RUN_CMD nix-env -e "$1" > $DRY_RUN_NULL 2>&1
+            run --silence nix-env -e "$1"
         fi
     fi
 }
@@ -161,6 +161,9 @@ nix-env -q > /dev/null 2>&1 || true
 migrateProfile
 setupVars
 
+# Note, the DRY_RUN_CMD and DRY_RUN_NULL variables are deprecated and should not
+# be used inside the Home Manager project. They are provided here for backwards
+# compatibility.
 if [[ -v DRY_RUN ]] ; then
     _i "This is a dry run"
     export DRY_RUN_CMD=echo

modules/misc/dconf.nix

@@ -112,7 +112,7 @@ in {
             '($old[] - $new[])[]' \
           | while read -r key; do
               $VERBOSE_ECHO "Resetting dconf key \"$key\""
-              $DRY_RUN_CMD $DCONF_DBUS_RUN_SESSION dconf reset "$key"
+              run $DCONF_DBUS_RUN_SESSION dconf reset "$key"
             done
       '';
     in ''
@@ -128,7 +128,7 @@ in {
           "$newGenPath/${statePath}"
       fi
 
-      $DRY_RUN_CMD $DCONF_DBUS_RUN_SESSION ${pkgs.dconf}/bin/dconf load / < ${iniFile}
+      run $DCONF_DBUS_RUN_SESSION ${pkgs.dconf}/bin/dconf load / < ${iniFile}
 
       unset DCONF_DBUS_RUN_SESSION
     '');

modules/misc/uninstall.nix

@@ -31,19 +31,19 @@ in {
         nixProfileRemove home-manager-path
 
         if [[ -e $hmDataPath ]]; then
-            $DRY_RUN_CMD rm $VERBOSE_ARG -r "$hmDataPath"
+            run rm $VERBOSE_ARG -r "$hmDataPath"
         fi
 
         if [[ -e $hmStatePath ]]; then
-            $DRY_RUN_CMD rm $VERBOSE_ARG -r "$hmStatePath"
+            run rm $VERBOSE_ARG -r "$hmStatePath"
         fi
 
         if [[ -e $genProfilePath ]]; then
-            $DRY_RUN_CMD rm $VERBOSE_ARG "$genProfilePath"*
+            run rm $VERBOSE_ARG "$genProfilePath"*
         fi
 
         if [[ -e $legacyGenGcPath ]]; then
-            $DRY_RUN_CMD rm $VERBOSE_ARG "$legacyGenGcPath"
+            run rm $VERBOSE_ARG "$legacyGenGcPath"
         fi
       '';
   };

modules/misc/xdg-user-dirs.nix

@@ -137,7 +137,7 @@ in {
 
     home.activation.createXdgUserDirectories = mkIf cfg.createDirectories (let
       directoriesList = attrValues directories;
-      mkdir = (dir: ''$DRY_RUN_CMD mkdir -p $VERBOSE_ARG "${dir}"'');
+      mkdir = (dir: ''run mkdir -p $VERBOSE_ARG "${dir}"'');
     in lib.hm.dag.entryAfter [ "linkGeneration" ]
     (strings.concatMapStringsSep "\n" mkdir directoriesList));
   };

modules/misc/xfconf.nix

@@ -106,7 +106,7 @@ in {
     home.activation.xfconfSettings = hm.dag.entryAfter [ "installPackages" ]
       (let
         mkCommand = channel: property: value: ''
-          $DRY_RUN_CMD ${pkgs.xfce.xfconf}/bin/xfconf-query \
+          run ${pkgs.xfce.xfconf}/bin/xfconf-query \
             ${
               escapeShellArgs ([ "-c" channel "-p" "/${property}" ]
                 ++ (if value == null then
@@ -129,7 +129,7 @@ in {
           export DBUS_RUN_SESSION_CMD="${pkgs.dbus}/bin/dbus-run-session --dbus-daemon=${pkgs.dbus}/bin/dbus-daemon"
         fi
 
-        $DRY_RUN_CMD $DBUS_RUN_SESSION_CMD ${load}
+        run $DBUS_RUN_SESSION_CMD ${load}
 
         unset DBUS_RUN_SESSION_CMD
       '');

modules/programs/bat.nix

@@ -163,7 +163,7 @@ in {
         (
           export XDG_CACHE_HOME=${escapeShellArg config.xdg.cacheHome}
           $VERBOSE_ECHO "Rebuilding bat theme cache"
-          $DRY_RUN_CMD ${lib.getExe package} cache --build
+          run ${lib.getExe package} cache --build
         )
       '';
     }

modules/programs/gh.nix

@@ -143,7 +143,7 @@ in {
             trap "rm --force --recursive $TMP_DIR" EXIT
             cp "${ghHosts}" $TMP_DIR/
             export GH_CONFIG_DIR=$TMP_DIR
-            $DRY_RUN_CMD ${getExe cfg.package} help 2>&1 > $DRY_RUN_NULL
+            run --silence ${getExe cfg.package} help
             cp $TMP_DIR/hosts.yml "${ghHosts}"
           )
         fi

modules/programs/gpg.nix

@@ -282,7 +282,7 @@ in {
     home.activation = {
       createGpgHomedir =
         hm.dag.entryBetween [ "linkGeneration" ] [ "writeBoundary" ] ''
-          $DRY_RUN_CMD mkdir -m700 -p $VERBOSE_ARG ${escapeShellArg cfg.homedir}
+          run mkdir -m700 -p $VERBOSE_ARG ${escapeShellArg cfg.homedir}
         '';
 
       importGpgKeys = let
@@ -290,12 +290,11 @@ in {
 
         importKey = { source, trust, ... }:
           # Import mutable keys
-          optional cfg.mutableKeys
+          optional cfg.mutableKeys "run ${gpg} $QUIET_ARG --import ${source}"
-          "$DRY_RUN_CMD ${gpg} $QUIET_ARG --import ${source}"
 
           # Import mutable trust
           ++ optional (trust != null && cfg.mutableTrust)
-          ''$DRY_RUN_CMD importTrust "${source}" ${toString trust}'';
+          ''run importTrust "${source}" ${toString trust}'';
 
         anyTrust = any (k: k.trust != null) cfg.publicKeys;
 

modules/programs/mbsync.nix

@@ -287,7 +287,7 @@ in {
       home.activation = mkIf (mbsyncAccounts != [ ]) {
         createMaildir =
           hm.dag.entryBetween [ "linkGeneration" ] [ "writeBoundary" ] ''
-            $DRY_RUN_CMD mkdir -m700 -p $VERBOSE_ARG ${
+            run mkdir -m700 -p $VERBOSE_ARG ${
               concatMapStringsSep " " (a: a.maildir.absPath) mbsyncAccounts
             }
           '';

modules/programs/mu.nix

@@ -54,7 +54,7 @@ in {
       # In theory, mu is the only thing that creates that directory, and it is
       # only created during the initial index.
       if [[ ! -d "${dbLocation}" ]]; then
-        $DRY_RUN_CMD ${
+        run ${
           getExe cfg.package
         } init ${maildirOption} ${myAddresses} $VERBOSE_ARG;
       fi

modules/programs/taskwarrior.nix

@@ -110,13 +110,13 @@ in {
       if [[ ! -s "${userConf}" ]]; then
         # Ensure file's existence
         if [[ -v DRY_RUN ]]; then
-          $DRY_RUN_CMD echo "include ${homeConf}" ">" "${userConf}"
+          run echo "include ${homeConf}" ">" "${userConf}"
         else
           echo "include ${homeConf}" > "${userConf}"
         fi
       elif ! grep -qF "include ${homeConf}" ${escapeShellArg userConf}; then
         # Add include statement for Home Manager generated config.
-        $DRY_RUN_CMD sed -i '1i include ${homeConf}' ${escapeShellArg userConf}
+        run sed -i '1i include ${homeConf}' ${escapeShellArg userConf}
       fi
     '';
   };

modules/programs/vscode.nix

@@ -257,9 +257,9 @@ in {
             "${extensionPath}/.extensions-immutable.json" = {
               text = extensionJson;
               onChange = ''
-                $DRY_RUN_CMD rm $VERBOSE_ARG -f ${extensionPath}/{extensions.json,.init-default-profile-extensions}
+                run rm $VERBOSE_ARG -f ${extensionPath}/{extensions.json,.init-default-profile-extensions}
                 $VERBOSE_ECHO "Regenerating VSCode extensions.json"
-                $DRY_RUN_CMD ${getExe cfg.package} --list-extensions > /dev/null
+                run ${getExe cfg.package} --list-extensions > /dev/null
               '';
             };
           })

modules/services/dropbox.nix

@@ -55,17 +55,17 @@ in {
         ExecStop = "${dropboxCmd} stop";
         ExecStart = toString (pkgs.writeShellScript "dropbox-start" ''
           # ensure we have the dirs we need
-          $DRY_RUN_CMD ${pkgs.coreutils}/bin/mkdir $VERBOSE_ARG -p \
+          run ${pkgs.coreutils}/bin/mkdir $VERBOSE_ARG -p \
             ${homeBaseDir}/{.dropbox,.dropbox-dist,Dropbox}
 
           # symlink them as needed
           if [[ ! -d ${config.home.homeDirectory}/.dropbox ]]; then
-            $DRY_RUN_CMD ${pkgs.coreutils}/bin/ln $VERBOSE_ARG -s \
+            run ${pkgs.coreutils}/bin/ln $VERBOSE_ARG -s \
               ${homeBaseDir}/.dropbox ${config.home.homeDirectory}/.dropbox
           fi
 
           if [[ ! -d ${escapeShellArg cfg.path} ]]; then
-            $DRY_RUN_CMD ${pkgs.coreutils}/bin/ln $VERBOSE_ARG -s \
+            run ${pkgs.coreutils}/bin/ln $VERBOSE_ARG -s \
               ${homeBaseDir}/Dropbox ${escapeShellArg cfg.path}
           fi
 

modules/systemd-activate.sh

@@ -110,5 +110,5 @@ function systemdPostReload() {
 oldGenPath="$1"
 newGenPath="$2"
 
-$DRY_RUN_CMD systemctl --user daemon-reload
+run systemctl --user daemon-reload
 systemdPostReload

modules/targets/darwin/fonts.nix

@@ -19,7 +19,7 @@ in {
 
         local f
         find -L "${fonts}" -type f -printf '%P\0' | while IFS= read -rd "" f; do
-          $DRY_RUN_CMD install $VERBOSE_ARG -Dm644 -T \
+          run install $VERBOSE_ARG -Dm644 -T \
             "${fonts}/$f" "${homeDir}/Library/Fonts/HomeManager/$f"
         done
       }

modules/targets/darwin/keybindings.nix

@@ -38,7 +38,7 @@ in {
     home.activation.setCocoaKeybindings =
       hm.dag.entryAfter [ "writeBoundary" ] ''
         $VERBOSE_ECHO "Configuring keybindings for the Cocoa Text System"
-        $DRY_RUN_CMD install -Dm644 $VERBOSE_ARG \
+        run install -Dm644 $VERBOSE_ARG \
           "${confFile}" "${homeDir}/Library/KeyBindings/DefaultKeyBinding.dict"
       '';
   };

modules/targets/darwin/user-defaults/default.nix

@@ -13,9 +13,9 @@ let
       cliFlags = lib.optionalString isLocal "-currentHost";
 
       toActivationCmd = domain: attrs:
-        "$DRY_RUN_CMD /usr/bin/defaults ${cliFlags} import ${
+        "run /usr/bin/defaults ${cliFlags} import ${escapeShellArg domain} ${
-          escapeShellArg domain
+          toDefaultsFile domain attrs
-        } ${toDefaultsFile domain attrs}";
+        }";
 
       nonNullDefaults =
         mapAttrs (domain: attrs: (filterAttrs (n: v: v != null) attrs))

tests/modules/programs/gpg/mutable-keyfiles.nix

@@ -22,10 +22,10 @@
     assertFileContains activate "unset GNUPGHOME QUIET_ARG keyId importTrust"
 
     assertFileRegex activate \
-      '^\$DRY_RUN_CMD @gnupg@/bin/gpg \$QUIET_ARG --import /nix/store/[0-9a-z]*-key1$'
+      '^run @gnupg@/bin/gpg \$QUIET_ARG --import /nix/store/[0-9a-z]*-key1$'
     assertFileRegex activate \
-      '^\$DRY_RUN_CMD importTrust "/nix/store/[0-9a-z]*-key1" 1$'
+      '^run importTrust "/nix/store/[0-9a-z]*-key1" 1$'
     assertFileRegex activate \
-      '^\$DRY_RUN_CMD @gnupg@/bin/gpg \$QUIET_ARG --import /nix/store/[0-9a-z]*-key2$'
+      '^run @gnupg@/bin/gpg \$QUIET_ARG --import /nix/store/[0-9a-z]*-key2$'
   '';
 }

tests/modules/programs/mu/basic-configuration.nix

@@ -19,6 +19,6 @@
       'if [[ ! -d "/home/hm-user/.cache/mu" ]]; then'
 
     assertFileContains activate \
-      '$DRY_RUN_CMD @mu@/bin/mu init --maildir=/home/hm-user/Mail --my-address=hm@example.com --my-address=foo@example.com $VERBOSE_ARG;'
+      'run @mu@/bin/mu init --maildir=/home/hm-user/Mail --my-address=hm@example.com --my-address=foo@example.com $VERBOSE_ARG;'
   '';
 }