From 4cad40753f929cf0671b167df89e0bd09cd2d71d Mon Sep 17 00:00:00 2001
From: vicrodh <103399283+vicrodh@users.noreply.github.com>
Date: Thu, 27 Aug 2026 10:37:23 -0600
Subject: [PATCH] docs(qt): correct how PowerShell leaves an empty backend env
 var

The parenthetical added in 1a01abde6 says `$null` removes the variable. It
does not, for the call the comment is about: PowerShell coerces `$null` to
String.Empty when binding a `string` parameter, so
`[Environment]::SetEnvironmentVariable('X', $null, 'Process')` leaves the name
PRESENT and empty, and a child process inherits it that way. That is the call
that produced the original observation.

`$env:X = $null` IS the one that removes it, so both spellings belong in the
comment rather than one standing for the other.

Measured on Windows 11, PowerShell 7.6.5, with a child that enumerates its own
environment rather than using cmd's `if defined` - which collapses "empty" and
"absent" and is what made an earlier reading of this look the other way:

  [Environment]::SetEnvironmentVariable('X', $null, 'Process')
  python -c "import os; print('X' in os.environ, repr(os.environ.get('X')))"
  -> True ''

  never set at all
  -> False

The POSIX half of the comment is unchanged and was already correct: `VAR= cmd`
delivers `Some("")`, verified the same way.

Comment only; no behaviour change.

cc
---
 crates/qbz-qt/src/main.rs | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/crates/qbz-qt/src/main.rs b/crates/qbz-qt/src/main.rs
index e2d971150..87aec133f 100644
--- a/crates/qbz-qt/src/main.rs
+++ b/crates/qbz-qt/src/main.rs
@@ -3040,10 +3040,14 @@ fn publish_home_sections(sections: &home_qt::DiscoverSections) {
 /// `var_os(..).is_some()` answers YES for an EMPTY value, and an empty value
 /// is exactly what a shell or a test harness leaves behind when it clears a
 /// variable rather than unsetting it: `QSG_RHI_BACKEND= ./qbz` on Linux, and
-/// `$env:QSG_RHI_BACKEND = ''` in PowerShell 7.5+ on Windows. (`$null` removes
-/// the variable instead.) The whole preference then silently stopped applying,
-/// the persisted Settings choice included, and the only clue was one info line
-/// claiming an explicit backend was present.
+/// on Windows either `$env:QSG_RHI_BACKEND = ''` or
+/// `[Environment]::SetEnvironmentVariable('QSG_RHI_BACKEND', $null, 'Process')`
+/// — PowerShell coerces `$null` to `String.Empty` for a `string` parameter, so
+/// that call leaves the name PRESENT and empty, and a child process inherits
+/// it that way. (`$env:QSG_RHI_BACKEND = $null` is the one that removes it.)
+/// The whole preference then silently stopped applying, the persisted Settings
+/// choice included, and the only clue was one info line claiming an explicit
+/// backend was present.
 ///
 /// `QBZ_RENDERER`, read a few lines below, has always filtered the empty
 /// string. This is the same rule for the two Qt variables.