29 Windows folders and environment variables

A package names places on a PC its author has never seen: "the program files folder", "this user's settings folder", "the Windows folder". On one PC the program files folder is C:\Program Files, on another D:\Program Files; the user is called someone different on each. This chapter explains how Windows names such places - environment variables, known folders and Windows Installer's folder properties - and when each name is turned into a real path.

29.1 What an environment variable is#

Every running program carries a small list of environment variables: names with text values, such as TEMP=C:\Users\<name>\AppData\Local\Temp. A program gets a copy of the list from the program that started it; changing its copy changes nothing for anyone else. Names are not case-sensitive: %TEMP%, %Temp% and %temp% are the same variable.

Each tool writes them its own way:

Where the list comes from: when a user logs on, Windows builds it from

• the system variables, the same for every user (HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment);
• the user's variables (HKCU\Environment); a user Path is added to the end of the system one;
• values Windows works out at logon: the user's name and profile folders, the domain, the logon server (HKCU\Volatile Environment), and the standard folders.

A change to the stored variables reaches only programs started afterwards. A package that sets a variable ([env.*], tutorial chapter 11) therefore asks for a new Command Prompt before it is seen.

29.2 The common variables#

Typical values on Windows 10 and 11 on drive C:; <name> is the user's account name.

Folders#

Older guides give paths such as C:\Documents and Settings\<name>\Application Data: those are Windows XP's. Since Windows Vista the profiles are under C:\Users, and ALLUSERSPROFILE became C:\ProgramData.

The two Program Files folders are why a 32-bit program asked for %ProgramFiles% gets C:\Program Files (x86): Windows gives each kind of program the folder of its own kind.

Not folders#

The Command Prompt also answers %CD%, %DATE%, %TIME%, %RANDOM% and %ERRORLEVEL%, but it makes them up when asked; they are not in the environment, and nothing else sees them.

29.3 Folders without a variable#

The desktop, the Start menu and its Programs folder, the Startup folder, the Fonts folder and Documents have no environment variable. Windows names them as known folders, and a program asks for one with SHGetKnownFolderPath. That is also the reliable way for the folders that do have a variable: whoever starts a program can give it any environment, and a user may have moved Documents or the desktop elsewhere (into OneDrive, for example), which only the known folder reflects.

29.4 Three moments#

A name becomes a path at one of three moments, and the moment decides whose path it is.

1. Build time, on the machine that runs rubrapack build. Nothing about the target PC is known yet. rubrapack's $(NAME) variables are replaced here; they never read the build machine's environment (pass a value with -D NAME=value).
2. Install time, on the target PC. Windows Installer works out its folder properties and the [%NAME] parts of formatted strings, for the user who installs. In a per-machine package installed by an administrator, the "local application data" folder is the administrator's.
3. Run time, whenever a program reads the value. A REG_EXPAND_SZ value holding %LOCALAPPDATA%\Hello\log gives every user their own folder, because each user's program expands it with that user's environment.

So a log folder for each user is written for run time:

[registry.LogDir]
root = "HKLM"
key = 'SOFTWARE\Example Software\Hello'
name = "LogDir"
type = "expand"
value = '%LOCALAPPDATA%\Hello\log'        # expanded by each user's program

whereas value = '[LocalAppDataFolder]Hello\log' would store the installing user's folder for everybody.

29.5 Windows Installer's names#

Windows Installer has its own property for most folders, worked out at install time:

Every folder property ends in a backslash, so [ProgramFiles64Folder]Hello needs none between. Beware of USERNAME: Windows Installer's property of that name is the name typed for registration, not the account; the account is LogonUser. Any variable without a property is reached as [%NAME].

29.6 In rubrapack#

rubrapack writes all these names one way, $(NAME), with Windows' spelling (letter case does not matter); $$ is a literal $. When the name is replaced depends on where it stands:

• At the start of a path, a folder: path = "$(ProgramFiles)/Hello", path = "$(LOCALAPPDATA)/Hello", path = "$(Fonts)". rubrapack turns it into the matching Windows Installer folder, or in an MSIX the matching package folder (tutorial chapter 4).
• In a value Windows Installer fills in - registry, environment and INI values, arguments, messages - the install-time form: '$(USERPROFILE)\notes' becomes [%USERPROFILE]\notes, and '$(LOCALAPPDATA)\Hello' becomes [LocalAppDataFolder]Hello (a folder property already ends with \, so the one after the name is dropped).
• In a type = "expand" registry value, the run-time form: '$(LOCALAPPDATA)\Hello\log' is stored as %LOCALAPPDATA%\Hello\log, which each user's program expands for that user.

So the log folder for each user from above is written

[registry.LogDir]
root = "HKLM"
key = 'SOFTWARE\Example Software\Hello'
name = "LogDir"
type = "expand"
value = '$(LOCALAPPDATA)\Hello\log'       # stored as %LOCALAPPDATA%\Hello\log

and without type = "expand" the same value would store the installing user's folder. The table of every name and what it becomes is in the Reference part (Windows names). An MSIX has no install time: a value that needs one is refused there (RP1612), while the run-time form works, since the program expands it.

29.7 Where this is used#

• Tutorial chapter 4: install folders and their bases.
• Tutorial chapter 11: registry values, environment variables and %TEMP%.
• Reference: Windows names, Registry values, Environment variables, Variables.