installer

# Firefox Windows Installer The Firefox installer gets users running Firefox as quickly and reliably as possible while integrating it into the Windows system. It is built on the NSIS (Nullsoft Scriptable Install System) framework, which compiles scripts in its custom language (plus native C++ plugins) into executable installers. We build four installer types: Stub Installer, Full Installer, MSI package (wraps the full installer), and MSIX package. There is also helper.exe (uninstaller + post-update + shortcuts). Read `references/build-and-test.md` before building or testing changes, `references/telemetry.md` before touching install/uninstall pings, `references/full-installer-options.md` for the full installer's CLI/INI surface, `references/file-map.md` to locate a script/include/doc by topic, `references/uac.md` before touching elevation logic, and `references/stub-installer.md` before touching the stub's HTML/CSS/JS UI or the WebBrowser plugin. --- # 1. Architecture ## 1.1 Stub installer The default installer most users see. A tiny download (200-300 KB) that downloads and runs the full installer silently. It offers no options except an optional profile cleanup prompt for returning users. - Main script: `browser/installer/windows/nsis/stub.nsi` - Structure is unusual for NSIS: one empty section, no predefined pages; all work is in two custom pages (`createProfileCleanup` and `createInstall`) - GUI is built with HTML/CSS/JS rendered via the Windows `IWebBrowser2` control (IE-based), driven by the custom WebBrowser NSIS plugin ### Execution flow 1. `.onInit` checks system requirements, selects 32/64-bit, looks for existing install to pave over, displays UAC prompt, initializes variables and GUI 2. `createProfileCleanup` optionally offers profile cleanup (same as about:support refresh) 3. `createInstall` draws the download/install UI, starts a blurb rotation timer, runs `StartDownload` 4. `StartDownload` kicks off the InetBgDl plugin for background download, starts `OnDownload` timer (200ms) 5. `OnDownload` checks download status, retries on failure, updates progress bar, verifies and runs the full installer when complete 6. `CheckInstall` waits for the full installer to exit, deletes the file 7. `FinishInstall` copies post-signing data, waits for the app to launch (requesting profile cleanup if selected) 8. Once the app is running and has shown a window, the stub sends its ping and exits ### Architecture selection 64-bit is selected only if: (1) 64-bit OS, (2) strictly more than 2 GB RAM, (3) no incompatible third-party software. Otherwise 32-bit. ### Install scope Automatically selected based on privileges. Rejecting the UAC prompt results in a per-user installation. No UI for this choice. ### Install location Looks for existing same-channel installation with matching architecture to pave over. If none found, uses a hard-coded default based on architecture, scope, and channel. ### Profile cleanup Shown when helpful. Two variants: "paveover" (overwriting existing install) and "reinstall" (new install). Triggers the same refresh as about:support. Decision logic: 1. Find default Firefox profile; if none, skip 2. Look for existing same-channel installation via registry 3. Check if default profile's last-used version is 2+ versions behind current; if so, show prompt ### GUI and WebBrowser plugin IE8 rendering mode, limited image/font formats, fixed window size, and the `ShowPage`/`RegisterCustomFunction`/`CreateTimer` WebBrowser plugin API used to drive the HTML/CSS/JS UI — see `references/stub-installer.md`. ## 1.2 Full installer The "real" installer that does the actual work. Uses a traditional wizard interface. Can be launched by the stub or standalone. Produces setup.exe (30-40 MB). - Main script: `browser/installer/windows/nsis/installer.nsi` - Heavy lifting in `toolkit/mozapps/installer/windows/nsis/common.nsh` - Writes `installation_telemetry.json` to the install location (read by Firefox for telemetry) — see `references/telemetry.md` - If not launched by the stub, sends an install ping on exit — see `references/telemetry.md` - Can access NSIS plugins written in C++ - Full CLI/INI option surface: `references/full-installer-options.md` ## 1.3 Helper (helper.exe) Contains the uninstaller, a post-update routine, and default browser/shortcut utilities. Two main files: `uninstaller.nsi` (entry point + uninstall logic) and `shared.nsh` (other functions). ### Uninstaller Philosophy: remove everything the installer creates, nothing it doesn't. - Removes all installer-created registry entries (including very old versions) - Deletes known application files using the `precomplete` file (auto-generated list of all app files) - Leaves the install directory if any unknown files remain - Runs maintenance service uninstaller if this was the only Firefox using it - Cancels any BITS jobs for this installation - Uploads the uninstall ping — see `references/telemetry.md` - Profiles and user-generated files are NOT removed ### PostUpdate Runs after an update via `/PostUpdate` switch. Maintains system integration objects (version numbers in registry, shortcut renaming, maintenance service updates, DLL registration). Key facts: - Runs after its own code has been updated, so changes take effect immediately in the first build containing a patch - Runs twice: once elevated (HKLM entries) and once as regular user (HKCU entries) - Windows-only; cannot fix things up on other platforms ### Default browser and shortcut handling - `/ShowShortcuts` — add application to Open With - `/HideShortcuts` — remove application from Open With - `/SetAsDefaultAppGlobal` — make default browser (system-wide) - `/SetAsDefaultAppUser` — make default browser (invoked by Firefox preferences) On Windows 10+, SetAsDefault commands only write necessary registry entries since the settings app controls defaults. ShowShortcuts/HideShortcuts are never called (SPAD control panel no longer exists). ## 1.4 MSI package A Windows Installer package for enterprise deployment. NOT a "true" MSI — it wraps the full installer. The full installer runs inside the MSI just as if launched normally. Built with WiX tools from `browser/installer/windows/msi/installer.wxs`. - Build: `./mach repackage msi` - Most of the WiX file passes MSI properties through as CLI arguments to the full installer - Cannot uninstall Firefox via standard MSI tools (limitation of the wrapper approach) ## 1.5 MSIX package A full participant in the Windows modern app packaging system. Distributed, installed, updated, repaired, and uninstalled entirely via that system. Firefox's built-in updater is always disabled in MSIX. Better than MSI for Windows 10+ enterprise deployment. - Build: `./mach repackage msix` - Can build unsigned packages with `--unsigned` (Windows 11 only) - Can sign locally with `--sign` or `./mach repackage sign-msix` - Channel-specific paths and assets (branding-aware) - Langpacks included as distribution extensions in shippable builds - `resources.pri` generated with `makepri.exe` from Windows SDK --- # 2. File locations Installer scripts and includes live under `browser/installer/windows/nsis/` (browser-level) and `toolkit/mozapps/installer/windows/nsis/` (toolkit-level shared utilities in `common.nsh`), with NSIS plugins in `other-licenses/nsis/Plugins/`, branding in `browser/branding/*/branding.nsi`, and docs in `browser/installer/windows/docs/`. See `references/file-map.md` for the full breakdown by script, include, branding, build config, localization, plugins, UI content, repackaging, and tests. --- # 3. NSIS language guide ## 3.1 Variables - Declared with `Var VarName` at the top of files, outside any section or function - Avoid `Var /GLOBAL` inside sections/functions; it works but is non-idiomatic - All variables are global, mutable, and only known at install-time - Access with `$VarName` syntax - Key built-in variables: `$INSTDIR` (install directory), `$EXEDIR` (executable directory) ## 3.2 Defines (symbols) - Compile-time constants, accessed with `${DefineName}` syntax - `!undef` a define when no longer needed to prevent accidental reuse - Key defines: `${BrandFullName}` (product name), `${FileMainEXE}` (main exe name) - `${GetLongPath}` returns the correctly formatted full path for a file ## 3.3 Registers - NSIS has registers `$0`-`$9` and `$R0`-`$R9` for temporary storage - Registers are global — a value set in a macro/function persists after execution - CRITICAL: always push registers before use and pop after, in FILO order, to avoid clobbering - Use registers in ascending order: `$0`, then `$1`, `$2`, `$3`, etc. (same for `$R0`, `$R1`, `$R2`, ...) - Convention: use `$R9` for macro return values ## 3.4 Functions vs macros - **Functions**: for code invoked repeatedly; cannot take arguments directly; use slightly less disk space - **Macros**: copy-paste code at invocation site; can take arguments; beware of variable clobbering since the code is inlined - Prefer macros when arguments are needed - Convention: define a `!define MacroName "!insertmacro MacroName"` shorthand so callers use `${MacroName}` syntax - Functions cannot take arguments natively; use stack Push/Pop or global variables instead ## 3.5 Parameter passing and return values - Stack-based: parameters pushed onto stack, functions use `Exch` and `Pop` - Push/Pop must follow FILO (First In Last Out) order - Return values: assign to a register (convention: `$R9`) or a user variable - Macros have no built-in return mechanism; use registers or global variables ## 3.6 LogicLib and conditional logic `${If}`, `${ElseIf}`, `${Else}`, `${EndIf}`, `${Unless}` are LogicLib macros that simplify conditional logic (replacing raw IntCmp/StrCmp gotos). Key constraint: LogicLib does NOT work recursively — a macro meant to be used as a right-hand operand of `${If}` cannot itself use `${If}` internally. For such macros, use raw `IntCmp`, `StrCmp`, or similar comparison instructions instead. ## 3.7 Conditional compilation - `!ifdef`, `!ifndef`, `!if`, `!else`, `!endif` for compile-time conditionals - `IfFileExists` for runtime file checks - `defines.nsi.in` uses `@VARIABLE@` substitution (Mozilla build system preprocessor) - Key defines: `MOZ_MAINTENANCE_SERVICE`, `MOZ_BITS_DOWNLOAD`, `MOZ_DEFAULT_BROWSER_AGENT`, `HAVE_64BIT_BUILD`, `_ARM64_` ## 3.8 Error handling - Check errors with `${If} ${Errors}` after operations - Use `IfFileExists` before file operations - Call `ClearErrors` at the start of functions/macros that check the error flag - `ClearErrors` can mask bugs if used carelessly; use with caution - Registry operations should handle missing keys gracefully - Common pattern: try HKLM, check errors, fall back to HKCU --- # 4. Codebase conventions ## 4.1 Naming - Standard macros: `${MacroName}` (e.g., `${SetHandlers}`, `${TouchStartMenuShortcut}`) - Uninstaller-only variants MUST use the `un.` prefix (e.g., `un.CheckForFilesInUse`) - If a macro is used in both installer and uninstaller, place it in `shared.nsh` and create both prefixed and unprefixed variants - Functions are called with `Call FunctionName` or `Call un.FunctionName` ## 4.2 Registry operations - Two main root keys: HKLM (system-wide, admin) and HKCU (current user only) - NSIS auto-creates parent keys when writing subkeys/values - Common value types: REG_SZ (string) and REG_DWORD (32-bit integer) - Write default value of a key by using empty string as value name - HKLM writes may fail in unelevated installs; always write fallback code for HKCU - Use `ClearErrors` before operations that may fail, then check `${If} ${Errors}` - Prefer commands that take an explicit root key argument over relying on `SetShellVarContext` ## 4.3 SetShellVarContext - `SetShellVarContext all` makes shell folder constants (`$DESKTOP`, `$SMPROGRAMS`, etc.) resolve to all-users paths AND sets `SHCTX` to HKLM for registry operations - `SetShellVarContext current` makes them resolve to current-user paths AND sets `SHCTX` to HKCU - It affects BOTH file system paths and registry operations (via the `SHCTX` root key) - Misreading or forgetting to restore the context is a common source of bugs - When possible, favor registry commands that explicitly take a root key (HKLM/HKCU) over relying on `SHCTX` - If you must use it, always restore it to the expected value after your operation - `control_utils.nsh` provides helpers: `${SetShellVarContextToValue}` and `${SwapShellVarContext}` ## 4.4 Code style - Keep lines reasonable in length - Use `; comment` style for inline comments (not `# comment`) - Section organization follows: PreInit -> Init -> InstallTypes -> Pages -> Sections -> Functions - Delete files with `Delete`, not `RMDir` (which is for directories) --- # 5. UAC and elevation All installer scripts declare `RequestExecutionLevel user` — they do NOT request admin at startup. Elevation is lazy, via the UAC plugin (`${ElevateUAC}`/`${UnloadUAC}` in common.nsh), and degrades gracefully to HKCU if declined or unavailable. After elevation, scripts test-write to HKLM to decide `$RegHive` (HKLM or HKCU) and set `SetShellVarContext` accordingly. When elevated code needs to run a user-level operation (e.g. shortcuts), it uses the dual-context pattern: detect the `/UAC:` flag with `${GetOptions}`, and if present, call `UAC::ExecCodeSegment` on a `GetFunctionAddress` of the user-level function instead of calling it directly. See `references/uac.md` for the full UAC plugin function reference, the elevation flow, the dual-context code pattern, and how elevation differs between the full installer, stub installer, and uninstaller.