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
This commit is contained in:
vicrodh committed 2026-08-27 10:37:23 -06:00
1 parent f9b139b441
commit 4cad40753f
1 file changed
+8 -4
+8 -4
View File
@@ -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.