stdenv: substituteStream: deprecate --replace in favor of --replace-{…

…fail,warn,quiet}

doc/languages-frameworks/emscripten.section.md

@@ -86,9 +86,9 @@ One advantage is that when `pkgs.zlib` is updated, it will automatically update
 
  postPatch = pkgs.lib.optionalString pkgs.stdenv.isDarwin ''
  substituteInPlace configure \
- --replace '/usr/bin/libtool' 'ar' \
- --replace 'AR="libtool"' 'AR="ar"' \
- --replace 'ARFLAGS="-o"' 'ARFLAGS="-r"'
+ --replace-fail '/usr/bin/libtool' 'ar' \
+ --replace-fail 'AR="libtool"' 'AR="ar"' \
+ --replace-fail 'ARFLAGS="-o"' 'ARFLAGS="-r"'
  '';
 })
 ```

doc/languages-frameworks/rust.section.md

@@ -700,7 +700,7 @@ with import <nixpkgs> {};
  hello = attrs: lib.optionalAttrs (lib.versionAtLeast attrs.version "1.0") {
  postPatch = ''
  substituteInPlace lib/zoneinfo.rs \
- --replace "/usr/share/zoneinfo" "${tzdata}/share/zoneinfo"
+ --replace-fail "/usr/share/zoneinfo" "${tzdata}/share/zoneinfo"
  '';
  };
  };

doc/stdenv/platform-notes.chapter.md

@@ -54,7 +54,7 @@ Some common issues when packaging software for Darwin:
  # ...
  prePatch = ''
  substituteInPlace Makefile \
- --replace '/usr/bin/xcrun clang' clang
+ --replace-fail '/usr/bin/xcrun clang' clang
  '';
  }
  ```

doc/stdenv/stdenv.chapter.md

@@ -230,9 +230,9 @@ stdenv.mkDerivation rec {
 
  postInstall = ''
  substituteInPlace $out/bin/solo5-virtio-mkimage \
- --replace "/usr/lib/syslinux" "${syslinux}/share/syslinux" \
- --replace "/usr/share/syslinux" "${syslinux}/share/syslinux" \
- --replace "cp " "cp --no-preserve=mode "
+ --replace-fail "/usr/lib/syslinux" "${syslinux}/share/syslinux" \
+ --replace-fail "/usr/share/syslinux" "${syslinux}/share/syslinux" \
+ --replace-fail "cp " "cp --no-preserve=mode "
 
  wrapProgram $out/bin/solo5-virtio-mkimage \
  --prefix PATH : ${lib.makeBinPath [ dosfstools mtools parted syslinux ]}
@@ -1253,9 +1253,20 @@ postInstall = ''
 
 Performs string substitution on the contents of \<infile\>, writing the result to \<outfile\>. The substitutions in \<subs\> are of the following form:
 
-#### `--replace` \<s1\> \<s2\> {#fun-substitute-replace}
+#### `--replace-fail` \<s1\> \<s2\> {#fun-substitute-replace-fail}
 
 Replace every occurrence of the string \<s1\> by \<s2\>.
+Will error if no change is made.
+
+#### `--replace-warn` \<s1\> \<s2\> {#fun-substitute-replace-warn}
+
+Replace every occurrence of the string \<s1\> by \<s2\>.
+Will print a warning if no change is made.
+
+#### `--replace-quiet` \<s1\> \<s2\> {#fun-substitute-replace-quiet}
+
+Replace every occurrence of the string \<s1\> by \<s2\>.
+Will do nothing if no change can be made.
 
 #### `--subst-var` \<varName\> {#fun-substitute-subst-var}
 
@@ -1269,8 +1280,8 @@ Example:
 
 ```shell
 substitute ./foo.in ./foo.out \
- --replace /usr/bin/bar $bar/bin/bar \
- --replace "a string containing spaces" "some other text" \
+ --replace-fail /usr/bin/bar $bar/bin/bar \
+ --replace-fail "a string containing spaces" "some other text" \
  --subst-var someVar
 ```
 

nixos/doc/manual/release-notes/rl-2405.section.md

@@ -160,6 +160,8 @@ The pre-existing [services.ankisyncd](#opt-services.ankisyncd.enable) has been m
 - The option [`services.nextcloud.config.dbport`] of the Nextcloud module was removed to match upstream.
  The port can be specified in [`services.nextcloud.config.dbhost`](#opt-services.nextcloud.config.dbhost).
 
+- `stdenv`: The `--replace` flag in `substitute`, `substituteInPlace`, `substituteAll`, `substituteAllStream`, and `substituteStream` is now deprecated if favor of the new `--replace-fail`, `--replace-warn` and `--replace-quiet`. The deprecated `--replace` equates to `--replace-warn`.
+
 - The Yama LSM is now enabled by default in the kernel, which prevents ptracing
  non-child processes. This means you will not be able to attach gdb to an
  existing process, but will need to start that process from gdb (so it is a

pkgs/stdenv/generic/setup.sh

@@ -815,15 +815,33 @@ fi
 ######################################################################
 # Textual substitution functions.
 
+# only log once, due to max logging limit on hydra
+_substituteStream_has_warned_replace_deprecation=""
 
 substituteStream() {
  local var=$1
  local description=$2
  shift 2
 
  while (( "$#" )); do
+ local is_required=1
+ local is_quiet=""
  case "$1" in
+ --replace-quiet)
+ is_quiet=1
+ ;&
  --replace)
+ # deprecated 2023-11-22
+ # this will either get removed, or switch to the behaviour of --replace-fail in the future
+ if [ -z "$_substituteStream_has_warned_replace_deprecation" ]; then
+ echo "substituteStream(): WARNING: '--replace' is deprecated, use --replace-{fail,warn,quiet}. ($description)" >&2
+ _substituteStream_has_warned_replace_deprecation=1
+ fi
+ ;&
+ --replace-warn)
+ is_required=""
+ ;&
+ --replace-fail)
  pattern="$2"
  replacement="$3"
  shift 3
@@ -832,7 +850,14 @@ substituteStream() {
  eval "$var"'=${'"$var"'//"$pattern"/"$replacement"}'
  if [ "$pattern" != "$replacement" ]; then
  if [ "${!var}" == "$savedvar" ]; then
- echo "substituteStream(): WARNING: pattern '$pattern' doesn't match anything in $description" >&2
+ if [ -z "$is_required" ]; then
+ if [ -z "$is_quiet" ]; then
+ echo "substituteStream(): WARNING: pattern '$pattern' doesn't match anything in $description" >&2
+ fi
+ else
+ echo "substituteStream(): ERROR: pattern '$pattern' doesn't match anything in $description" >&2
+ return 1
+ fi
  fi
  fi
  ;;