treewide: deprecate `VERBOSE_ECHO`

The shell function `verboseEcho` can be used in its stead.

docs/release-notes/rl-2405.md

@@ -60,6 +60,29 @@ This release has the following notable changes:
   their use may in the future trigger a warning message and eventually
   they may be removed entirely.
 
+- Similarly, the use of `$VERBOSE_ECHO` in activation script blocks is
+  deprecated. Instead use the new shell function
+  {command}`verboseEcho`. That is,
+
+  ```nix
+  home.activation.doThing = config.lib.dag.entryAnywhere ''
+    $VERBOSE_ECHO "Doing the thing"
+  ''
+  ```
+
+  should now be expressed
+
+  ```nix
+  home.activation.doThing = config.lib.dag.entryAnywhere ''
+    verboseEcho "Doing the thing"
+  ''
+  ```
+
+  See the description of [home.activation](#opt-home.activation) for
+  more. The deprecated variable will continue to work for now but its
+  use may in the future trigger a warning message and eventually it
+  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

lib/bash/home-manager.sh

@@ -48,6 +48,12 @@ function noteEcho() {
     echo "${noteColor}$*${normalColor}"
 }
 
+function verboseEcho() {
+    if [[ -v VERBOSE ]]; then
+        echo "$*"
+    fi
+}
+
 function _i() {
     local msgid="$1"
     shift
@@ -84,6 +90,12 @@ function _iNote() {
     echo -n "${normalColor}"
 }
 
+function _iVerbose() {
+    if [[ -v VERBOSE ]]; then
+        _i "$@"
+    fi
+}
+
 # Runs the given command on live run, otherwise prints the command to standard
 # output.
 #

modules/files.nix

@@ -103,7 +103,7 @@ in
             done
 
             if [[ -n $forced ]]; then
-              $VERBOSE_ECHO "Skipping collision check for $targetPath"
+              verboseEcho "Skipping collision check for $targetPath"
             elif [[ -e "$targetPath" \
                 && ! "$(readlink "$targetPath")" == $homeFilePattern ]] ; then
               # The target file already exists and it isn't a symlink owned by Home Manager.
@@ -184,7 +184,7 @@ in
 
             if [[ -e "$targetPath" && ! -L "$targetPath" ]] && cmp -s "$sourcePath" "$targetPath" ; then
               # The target exists but is identical – don't do anything.
-              $VERBOSE_ECHO "Skipping '$targetPath' as it is identical to '$sourcePath'"
+              verboseEcho "Skipping '$targetPath' as it is identical to '$sourcePath'"
             else
               # Place that symlink, --force
               # This can still fail if the target is a directory, in which case we bail out.
@@ -206,11 +206,11 @@ in
           for relativePath in "$@" ; do
             targetPath="$HOME/$relativePath"
             if [[ -e "$newGenFiles/$relativePath" ]] ; then
-              $VERBOSE_ECHO "Checking $targetPath: exists"
+              verboseEcho "Checking $targetPath: exists"
             elif [[ ! "$(readlink "$targetPath")" == $homeFilePattern ]] ; then
               warnEcho "Path '$targetPath' does not link into a Home Manager generation. Skipping delete."
             else
-              $VERBOSE_ECHO "Checking $targetPath: gone (deleting)"
+              verboseEcho "Checking $targetPath: gone (deleting)"
               run rm $VERBOSE_ARG "$targetPath"
 
               # Recursively delete empty parent directories.

modules/home-environment.nix

@@ -410,12 +410,12 @@ in
         output to {file}`/dev/null`, otherwise prints the command to standard
         output.
 
-        A script block should also respect the
+        A script block should also respect the {var}`VERBOSE` variable, and if
-        {var}`VERBOSE` variable, and if set print
+        set print information on standard out that may be useful for debugging
-        information on standard out that may be useful for debugging
+        any issue that may arise. The variable {var}`VERBOSE_ARG` is set to
-        any issue that may arise. The variable
+        {option}`--verbose` if verbose output is enabled. You can also use the
-        {var}`VERBOSE_ARG` is set to
+        provided shell function {command}`verboseEcho`, which acts as
-        {option}`--verbose` if verbose output is enabled.
+        {command}`echo` when verbose output is enabled.
       '';
     };
 

modules/lib-bash/activation-init.sh

@@ -80,7 +80,7 @@ function setupVars() {
         oldGenPath="$(readlink -e "$genProfilePath")"
     fi
 
-    $VERBOSE_RUN _i "Sanity checking oldGenNum and oldGenPath"
+    _iVerbose "Sanity checking oldGenNum and oldGenPath"
     if [[ -v oldGenNum && ! -v oldGenPath
             || ! -v oldGenNum && -v oldGenPath ]]; then
         _i $'The previous generation number and path are in conflict! These\nmust be either both empty or both set but are now set to\n\n    \'%s\' and \'%s\'\n\nIf you don\'t mind losing previous profile generations then\nthe easiest solution is probably to run\n\n   rm %s/home-manager*\n   rm %s/current-home\n\nand trying home-manager switch again. Good luck!' \
@@ -138,6 +138,8 @@ function checkHomeDirectory() {
   fi
 }
 
+# Note, the VERBOSE_ECHO variable is deprecated and should not be used inside
+# the Home Manager project. It is provided here for backwards compatibility.
 if [[ -v VERBOSE ]]; then
     export VERBOSE_ECHO=echo
     export VERBOSE_ARG="--verbose"
@@ -152,7 +154,7 @@ _i "Starting Home Manager activation"
 
 # Verify that we can connect to the Nix store and/or daemon. This will
 # also create the necessary directories in profiles and gcroots.
-$VERBOSE_RUN _i "Sanity checking Nix"
+_iVerbose "Sanity checking Nix"
 nix-build --expr '{}' --no-out-link
 
 # Also make sure that the Nix profiles path is created.
@@ -169,7 +171,7 @@ if [[ -v DRY_RUN ]] ; then
     export DRY_RUN_CMD=echo
     export DRY_RUN_NULL=/dev/stdout
 else
-    $VERBOSE_RUN _i "This is a live run"
+    _iVerbose "This is a live run"
     export DRY_RUN_CMD=""
     export DRY_RUN_NULL=/dev/null
 fi
@@ -178,16 +180,16 @@ if [[ -v VERBOSE ]]; then
     _i 'Using Nix version: %s' "$(nix-env --version)"
 fi
 
-$VERBOSE_RUN _i "Activation variables:"
+_iVerbose "Activation variables:"
 if [[ -v oldGenNum ]] ; then
-    $VERBOSE_ECHO "  oldGenNum=$oldGenNum"
+    verboseEcho "  oldGenNum=$oldGenNum"
-    $VERBOSE_ECHO "  oldGenPath=$oldGenPath"
+    verboseEcho "  oldGenPath=$oldGenPath"
 else
-    $VERBOSE_ECHO "  oldGenNum undefined (first run?)"
+    verboseEcho "  oldGenNum undefined (first run?)"
-    $VERBOSE_ECHO "  oldGenPath undefined (first run?)"
+    verboseEcho "  oldGenPath undefined (first run?)"
 fi
-$VERBOSE_ECHO "  newGenPath=$newGenPath"
+verboseEcho "  newGenPath=$newGenPath"
-$VERBOSE_ECHO "  newGenNum=$newGenNum"
+verboseEcho "  newGenNum=$newGenNum"
-$VERBOSE_ECHO "  genProfilePath=$genProfilePath"
+verboseEcho "  genProfilePath=$genProfilePath"
-$VERBOSE_ECHO "  newGenGcPath=$newGenGcPath"
+verboseEcho "  newGenGcPath=$newGenGcPath"
-$VERBOSE_ECHO "  legacyGenGcPath=$legacyGenGcPath"
+verboseEcho "  legacyGenGcPath=$legacyGenGcPath"

modules/misc/dconf.nix

@@ -111,7 +111,7 @@ in {
             --slurpfile new "$newState" \
             '($old[] - $new[])[]' \
           | while read -r key; do
-              $VERBOSE_ECHO "Resetting dconf key \"$key\""
+              verboseEcho "Resetting dconf key \"$key\""
               run $DCONF_DBUS_RUN_SESSION dconf reset "$key"
             done
       '';

modules/programs/bat.nix

@@ -162,7 +162,7 @@ in {
       home.activation.batCache = hm.dag.entryAfter [ "linkGeneration" ] ''
         (
           export XDG_CACHE_HOME=${escapeShellArg config.xdg.cacheHome}
-          $VERBOSE_ECHO "Rebuilding bat theme cache"
+          verboseEcho "Rebuilding bat theme cache"
           run ${lib.getExe package} cache --build
         )
       '';

modules/programs/taskwarrior.nix

@@ -105,7 +105,7 @@ in {
     '';
 
     home.activation.regenDotTaskRc = hm.dag.entryAfter [ "writeBoundary" ] ''
-      $VERBOSE_ECHO "Ensuring generated taskwarrior config included in taskrc"
+      verboseEcho "Ensuring generated taskwarrior config included in taskrc"
 
       if [[ ! -s "${userConf}" ]]; then
         # Ensure file's existence

modules/programs/vscode.nix

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

modules/targets/darwin/keybindings.nix

@@ -37,7 +37,7 @@ in {
     # NOTE: just copy the files because symlinks won't be recognized by macOS
     home.activation.setCocoaKeybindings =
       hm.dag.entryAfter [ "writeBoundary" ] ''
-        $VERBOSE_ECHO "Configuring keybindings for the Cocoa Text System"
+        verboseEcho "Configuring keybindings for the Cocoa Text System"
         run install -Dm644 $VERBOSE_ARG \
           "${confFile}" "${homeDir}/Library/KeyBindings/DefaultKeyBinding.dict"
       '';

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

@@ -100,7 +100,7 @@ in {
     '';
 
     home.activation.setDarwinDefaults = hm.dag.entryAfter [ "writeBoundary" ] ''
-      $VERBOSE_ECHO "Configuring macOS user defaults"
+      verboseEcho "Configuring macOS user defaults"
       ${concatStringsSep "\n" activationCmds}
     '';
   };

xgettext

@@ -18,10 +18,12 @@ function run() {
            -k_iError:1 --flag=_i:1:c-format \
            -k_iWarn:1 --flag=_i:1:c-format \
            -k_iNote:1 --flag=_i:1:c-format \
+           -k_iVerbose:1 --flag=_i:1:c-format \
            -k_ip:1,2 --flag=_ip:1:c-format --flag=_ip:2:c-format \
            -k_ipError:1,2 --flag=_ip:1:c-format --flag=_ip:2:c-format \
            -k_ipWarn:1,2 --flag=_ip:1:c-format --flag=_ip:2:c-format \
            -k_ipNote:1,2 --flag=_ip:1:c-format --flag=_ip:2:c-format \
+           -k_ipVerbose:1,2 --flag=_ip:1:c-format --flag=_ip:2:c-format \
            --add-comments=translators: \
            -o "$output" -d "$domain" "$@"
 }