Bug 1325121 - Add some installer documentation to the tree. r?agashlin draft
authorMatt Howell <mhowell@mozilla.com>
Wed, 14 Feb 2018 10:01:38 -0800
changeset 759167 a5386f091feebffa1f4bb61089bb116532a71456
parent 759125 64b0835fd507bb7a6884c4dcd0bb33d5b9291ca9
push id100285
push usermhowell@mozilla.com
push dateFri, 23 Feb 2018 19:20:07 +0000
reviewersagashlin
bugs1325121
milestone60.0a1
Bug 1325121 - Add some installer documentation to the tree. r?agashlin This is not exhaustive technical documentation for every aspect of the installer code, but it's better than what we had, and it does contain the ping documentation that this bug was originally asking for. MozReview-Commit-ID: 5h7UwnAk4Iq
browser/installer/windows/docs/FullConfig.rst
browser/installer/windows/docs/FullInstaller.rst
browser/installer/windows/docs/Helper.rst
browser/installer/windows/docs/InstallerBuild.rst
browser/installer/windows/docs/StubArch.rst
browser/installer/windows/docs/StubConfig.rst
browser/installer/windows/docs/StubInstaller.rst
browser/installer/windows/docs/StubPing.rst
browser/installer/windows/docs/index.rst
browser/installer/windows/moz.build
new file mode 100644
--- /dev/null
+++ b/browser/installer/windows/docs/FullConfig.rst
@@ -0,0 +1,65 @@
+============================
+Full Installer Configuration
+============================
+
+Command-line Options
+--------------------
+
+The full installer provides a number of options that can be used either from the GUI or from silent mode. It accepts these two command-line options:
+
+``/S``
+  Silent installation. This option doesn't open the GUI, instead running the installation in the background using all the default settings. It's useful as part of a script for configuring a new system, for example.
+
+  For backwards compatibility, this option can also be spelled ``-ms``.
+
+``/INI=[absolute path to .ini file]``
+  Read configuration from an .ini file. Also triggers silent mode, but instead of using all the default settings, allows you to control them by providing a settings file.
+
+
+INI File Settings
+-----------------
+
+All of these settings should be placed into one section, called ``[Install]``, in the standard INI syntax. All of them are optional; they can be included or left out in any combination. Order does not matter.
+
+``InstallDirectoryPath``
+  Absolute path specifying the complete install location. This directory does not need to exist already (but it can).
+
+  If ``InstallDirectoryName`` is set, then this setting will be ignored.
+
+``InstallDirectoryName``
+  Name of the installation directory to create within Program Files. For example, if ``InstallDirectoryName`` is set to ``Firefox Release``, then the installation path will be something like ``C:\Program Files\Firefox Release``. The Program Files path used will be the correct one for the architecture of the application being installed and the locale/configuration of the machine; this setting is mainly useful to keep you from having to worry about those differences.
+
+  If this is set, then ``InstallDirectoryPath`` will be ignored.
+
+``TaskbarShortcut``
+  Set to ``false`` to disable pinning a shortcut to the taskbar. ``true`` by default. This feature only works on Windows 7 and 8; it isn't possible to create taskbar pins from the installer on later versions.
+
+``DesktopShortcut``
+  Set to ``false`` to disable creating a shortcut on the desktop. ``true`` by default.
+
+``StartMenuShortcuts``
+  Set to ``false`` to disable creating a Start menu shortcut. ``true`` by default. The name is historical; only one shortcut is ever created in the Start menu.
+
+``MaintenanceService``
+  Set to ``false`` to disable installing the Mozilla Maintenance Service. This will effectively prevent users from installing Firefox updates if they do not have write permissions to the installation directory. ``true`` by default.
+
+``RemoveDistributionDir``
+  Set to ``false`` to disable removing the ``distribution`` directory from an existing installation that's being paved over. By default this is ``true`` and the directory is removed.
+
+``PreventRebootRequired``
+  Set to ``true`` to keep the installer from taking actions that would require rebooting the machine to complete, normally because files are in use. This should not be needed under normal circumstances because no such actions should be required unless you're paving over a copy of Firefox that was running while the installer was trying to run, and setting this option in that case may result in an incomplete installation. ``false`` by default.
+
+``OptionalExtensions``
+  Set to ``false`` to disable installing any bundled extensions that are present. Normally none of these exist, except in special distributions of Firefox such as the one produced by Mozilla China or by other partner organizations. ``true`` by default.
+
+
+Example INI File
+~~~~~~~~~~~~~~~~
+::
+
+  [Install]
+  ; Semicolons can be used to add comments
+  InstallDirectoryName=Firefox Release
+  DesktopShortcut=false
+  MaintenanceService=false
+  OptionalExtensions=false
new file mode 100644
--- /dev/null
+++ b/browser/installer/windows/docs/FullInstaller.rst
@@ -0,0 +1,10 @@
+==============
+Full Installer
+==============
+
+The full installer is actually responsible for installing the browser; it's what the stub launches in order to do the "real" installing work, but it's also available separately. It uses a traditional "wizard" interface design, as is (somewhat) natively supported by NSIS. It can also be :doc:`configured <FullConfig>` to launch in a silent mode, suitable for scripting or managed deployments.
+
+The full installer's main script is `installer.nsi <https://searchfox.org/mozilla-central/source/browser/installer/windows/nsis/installer.nsi>`_, but most of the heavy lifting is done by the shared functions in `common.nsh <https://searchfox.org/mozilla-central/source/toolkit/mozapps/installer/windows/nsis/common.nsh>`_.
+
+.. toctree::
+   FullConfig
new file mode 100644
--- /dev/null
+++ b/browser/installer/windows/docs/Helper.rst
@@ -0,0 +1,32 @@
+======
+Helper
+======
+helper.exe contains the uninstaller, plus a routine that's run by the application updater after it applies an update, as well as a few utilities used for default browser handling and shortcut maintenance. It mainly consists of two files, uninstaller.nsi_, which is the main script and contains the entry point and the uninstall logic, and shared.nsh_, which contains most of the logic for the other functions.
+
+Uninstaller
+-----------
+The uninstaller may be the most straightforward of the installer components. The only complexity comes from a need to avoid accidentally removing any user files that may have found their way into the installation directory; the general philosophy of the uninstaller is to remove everything that the installer creates, and nothing that it doesn't.
+
+First, any registry entries the installer would have created are removed, even ones only used by very old installer versions. Then all the files that the uninstaller knows were created by the installer or are owned by the application are deleted, or flagged for deletion on reboot if any are in use. There are a few hard-coded directories that are known to be safe to delete (for example, the distribution directory, and any temporary directories created by the updater). For a list of application files that are safe to uninstall, we read a file from the application directory called ``precomplete``. This file is mainly used to tell the updater what it should do to clean out the directory when applying a complete update (one that replaces all application files), but that means it contains a handy auto-generated list of all application files, so it can be reused for uninstallation. If the application directory is empty after that, then it is removed, but it's left alone if any files are still present. Finally, if the copy of Firefox that was just uninstalled is the only one that was using the maintenance service, the maintenance service uninstaller is also run.
+
+Note that profiles and any other user-generated files (e.g., crash reports) are specifically not uninstalled.
+
+PostUpdate
+----------
+At the end of an application update cycle, after the new files are in place, the updater invokes the helper with the ``/PostUpdate`` command-line switch. The PostUpdate function fills a grab bag of responsibilities which are all focused around maintaining system integration objects created by the installer. For example, a number of registry entires contain the version number, so that has to be changed on updates. If the branding name of the application changes and shortcuts have to be renamed, that's done here as well. For one counterexample, changing icons does not require any code in PostUpdate, or anywhere else; new icons are automatically picked up by the shell. The PostUpdate function also keeps the maintenance service up to date.
+
+It's important to remember that PostUpdate is, indeed, post-update. It doesn't run until after its own code has already been updated. This makes it really the only phase of the update process where changes can go into affect immediately in the first build that contains a patch, instead of having to wait for the next update after that. This makes it a good place to put anything that needs to be done before the new version of the application can run; this includes things like registering DLL's, which the installer also handles, but that PostUpdate has to take care of for existing installations.
+
+It's also important to remember that PostUpdate, being part of the installer code, only exists on Windows, so it can't be used to fix things up on other platforms the same way.
+
+Default Browser and Shortcut Handling
+-------------------------------------
+Windows versions older than 10 contain a control panel called Set Program Access and Defaults, or SPAD. As the name suggests, this was the UI for setting default programs for classes of activities ("web browser" or "e-mail client" for example), as the Windows 10 default program settings page is, but it also controls program "access," which is typically defined as whether or not shortcuts for the program exist. To support this interface, an application has to register a set of commands that the interface can invoke to hide or show the shortcuts, and to have the application make itself the default. We implement these actions in helper.exe; they're triggered by invoking it with the command-line switches ``/ShowShortcuts``, ``/HideShortcuts``, or ``/SetAsDefaultAppGlobal``.
+
+The helper also implements the ``/SetAsDefaultAppUser`` switch, which is invoked by the "Make Default" button in the Firefox preferences UI.
+
+On Windows 10 neither SetAsDefaultAppUser nor SetAsDefaultAppGlobal is effective because the default programs settings can only be modified by the Windows settings app. However they do still write the registry entries that are needed to get us an entry in the system default browser menu, should those entries not already exist (the installer always creates them, but running Firefox without having run the installer is supported). ShowShortcuts and HideShortcuts are never called on Windows 10 because the SPAD control panel no longer exists.
+
+
+.. _uninstaller.nsi: https://searchfox.org/mozilla-central/source/browser/installer/windows/nsis/uninstaller.nsi
+.. _shared.nsh: https://searchfox.org/mozilla-central/source/browser/installer/windows/nsis/shared.nsh
new file mode 100644
--- /dev/null
+++ b/browser/installer/windows/docs/InstallerBuild.rst
@@ -0,0 +1,49 @@
+===============
+Installer Build
+===============
+
+How to build the installers
+---------------------------
+
+The easiest way to build an installer in your local tree is to run ``mach build installer``. The finished installers will be in ``$OBJDIR/dist/install/sea/``. You have to have a build of the application already done before that will work, but `artifact builds <https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Build_Instructions/Artifact_builds>`_ are supported, so that can save you a lot of time if you're only doing installer work.
+
+You'll also need to be on a Windows machine; the installer build depends on tools that aren't available for other platforms.
+
+Stub installer
+~~~~~~~~~~~~~~
+
+The stub installer probably won't be built by default in a local tree; normally unless the build has been set to use one of the official update channels, only the full installer is built. If you need to work on the stub installer, you can override the default and get one built along with the full installer by adding ``export MOZ_STUB_INSTALLER=1`` to your mozconfig.
+
+Uninstaller
+~~~~~~~~~~~
+
+The uninstaller is built as part of the main application build, not the installer target, so ``mach build`` is what will get you an uninstaller. You'll find it at ``$OBJDIR/dist/bin/uninstaller/helper.exe``.
+
+Branding
+~~~~~~~~
+
+By default local builds use "unofficial" branding, which somewhat resembles a previous version of the Nightly branding, but is designed not to resemble any official channel too closely.
+
+But sometimes you'll need to test installers that are built using one or more of the official channel branding configurations, perhaps to try out different strings, make sure different sets of art look good, or to test behavior around installing multiple channels at the same time.
+
+You can build installers (and the entire application) with official branding by adding ``ac_add_options --with-branding=browser/branding/{nightly|aurora|official}`` to your mozconfig (the default branding is ``browser/branding/unofficial``).
+
+Build process
+-------------
+
+Both the full and stub installers are built through a similar process, which is summarized here along with references to the relevant bits of code.
+
+Most of this procedure is done in `makensis.mk <http://searchfox.org/mozilla-central/source/toolkit/mozapps/installer/windows/nsis/makensis.mk>`_.
+
+0. The application has to be in a packaged state, so the equivalent of ``mach package`` is run.
+1. All required files are copied into the instgen directory. This includes .nsi and .nsh script files, plugin DLL files, image and icon files, and the 7-zip SFX module and its configuration files.
+2. The NSIS scripts are compiled, resulting in setup.exe and setup-stub.exe (if building the stub is enabled).
+3. The 7-zip SFX module is run through UPX.
+4. The application files and the full installer setup.exe are compressed together into one 7-zip file.
+5. The stub installer is compressed into its own 7-zip file.
+6. The (UPX-packed) 7-zip SFX module, the correct configuration data, and the 7-zip file containing the application files and setup.exe are concatenated together. This results in the final full installer.
+7. The (still UPX-packed) 7-zip SFX module, the correct configuration data, and the 7-zip file containing the stub installer are concatenated together. This results in the final stub installer.
+
+
+If this is an official build running on Mozilla automation infrastructure, then after this the installers will be signed, like other build products. Release engineering owns that process, it's not within the scope of this documentation.
+
new file mode 100644
--- /dev/null
+++ b/browser/installer/windows/docs/StubArch.rst
@@ -0,0 +1,16 @@
+===========================
+Stub Installer Architecture
+===========================
+
+The stub is called a stub because it doesn't actually install anything. It's just a GUI frontend that downloads and runs the full installer in silent mode. The exact full installer that will be downloaded isn't baked into the stub; the channel and the locale (which are baked in) are sent in a request to the Bouncer service, which uses that information to redirect to the URL of the specific full installer file.
+
+The main stub installer source code file is `stub.nsi <https://searchfox.org/mozilla-central/source/browser/installer/windows/nsis/stub.nsi>`_. Even though the stub installer doesn't install anything, it's still built on NSIS, using it largely as a GUI framework. This means the structure of stub.nsi is a bit odd for an NSIS script. There's only one section, and it's empty, and there are no predefined pages used (including no instfiles page, which we get a warning from the compiler about). The work is all done in two custom pages, createProfileCleanup and createInstall, and the functions called by those two pages. The basic execution flow is this:
+
+1. .onInit checks basic system requirements, determines whether we should install a 64-bit or a 32-bit build, looks for an existing installation that we should try to pave over, displays a UAC prompt, and initializes lots of variables and GUI objects.
+2. createProfileCleanup determines if a profile cleanup prompt should be offered (see the ShouldPromptForProfileCleanup function), and draws the UI for that if so.
+3. createInstall draws the UI for the download/install page, kicks off the periodic timer that swaps out the blurb text every few seconds, and runs StartDownload.
+4. StartDownload invokes the InetBgDl plugin to begin the full installer download on a background thread. It then starts a periodic timer for the OnDownload function.
+5. Every time OnDownload runs (every 200 ms), it checks the status of the background download, retries or restarts if the download has failed, updates the progress bar if the download is still running, and verifies and runs the full installer if the download is complete.
+6. CheckInstall waits for the full installer to exit, then deletes the file.
+7. FinishInstall copies the post-signing data, then waits for the application to launch.
+8. Once the installed application is running and has shown a window (or if another copy was already running), the stub sends its ping and then exits.
new file mode 100644
--- /dev/null
+++ b/browser/installer/windows/docs/StubConfig.rst
@@ -0,0 +1,38 @@
+============================
+Stub Installer Configuration
+============================
+
+The stub installer doesn't offer many options to the user, most of its configuration is automatic and implicit. But there are two things the user can control, and here we'll discuss those and the automated settings.
+
+Architecture
+------------
+The stub installer automatically selects whether to install a 32-bit or a 64-bit build of Firefox. 64-bit will be selected only if these conditions all pass:
+
+1. The operating system is a 64-bit build.
+2. The system has enough physical memory installed. Currently an amount strictly greater than 2 GB is required (that is, exactly 2 GB is not considered enough).
+3. No third-party software that is incompatible with the 64-bit build is present on the system.
+
+If any of the above conditions is not satisfied, a 32-bit build is installed.
+
+Scope
+-----
+We support creating the installation in either a machine or a per-user scope. This affects whether application files, shortcuts, and registry entires are created in locations that are accessible to any user on the machine or locations that are specific to a particular user. Even in the full installer there is no UI for configuring which scope is selected; instead both installers automatically select a scope based on whether they have the privileges needed to perform a machine scope installation. This means a user with those privileges can effectively control the scope by the selection they make in the Windows UAC prompt; rejecting it will mean that the installer doesn't see that user as an administrator and will perform a per-user installation.
+
+Install Location
+----------------
+The user doesn't have any control over the install location used by the stub. To determine the location that will be used, first the stub looks for any existing installations of the same channel of Firefox. If it finds one of those and the architecture of that installation is the same as the one that's been selected for the new one, then the path for the new install will be set to the same as that install, effectively overwriting it. This allows the stub to be used as a repair method for broken installations. If there isn't any existing installation fitting those criteria, then a hard-coded default is selected based on the architecture, scope, and channel.
+
+Profile Cleanup
+---------------
+If the stub installer detects that this could be a helpful thing to do, it will start off the installation by offering to clean up the user's Firefox profile. This is the same cleanup that's triggered by the "refresh" button in about:support, and it's performed by the same Firefox code (the stub really just asks the browser to do the cleanup using a command-line parameter, it doesn't try to perform the operation itself). The user can control whether this cleanup is done by toggling a checkbox that's shown before the installation begins.
+
+There are two variations of the profile cleanup prompt that can be shown to the user, one that appears if the new installation would overwrite an existing one (the "paveover" prompt) and another if it would be a new installation (the "reinstall" prompt). The only difference is the text that the user sees, the two function identically.
+
+This is the procedure that determines when one of the two cleanup prompts is shown:
+
+1. Look for the current default Firefox profile. If there are no profiles or none is set as the default, don't show either prompt.
+2. Look for an existing installation by searching the registry for any copies of Firefox that are registered for potential file type associations. If none exist, show the reinstall prompt.
+3. Check if the existing installation is for the same channel that's being installed now. If not, don't show either prompt.
+4. Check the version of Firefox that the default profile we found in step 1 was last used with. This information comes from the profile's compatibility.ini file. If that version is more than 2 versions behind the current version, show the paveover prompt. Otherwise, don't show either prompt. Information about the current version is taken from `<https://product-details.mozilla.org/1.0/firefox_versions.json>`_.
+
+
new file mode 100644
--- /dev/null
+++ b/browser/installer/windows/docs/StubInstaller.rst
@@ -0,0 +1,11 @@
+==============
+Stub Installer
+==============
+
+The stub installer is the default installer interface that most users installing Firefox will see. It's a tiny download (200-300 KB), so it gets the user into the product experience quickly. It's also a highly streamlined experience; there are no options or prompts offered, except in the case of a returning user (see Profile Cleanup). Running the stub installer immediately starts downloading and installing the browser, and automatically runs the new installation and exits when it's done.
+
+
+.. toctree::
+  StubConfig
+  StubPing
+  StubArch
new file mode 100644
--- /dev/null
+++ b/browser/installer/windows/docs/StubPing.rst
@@ -0,0 +1,159 @@
+=========
+Stub Ping
+=========
+
+When the stub installer completes with almost any result [1]_, it generates a ping containing some data about the system and about how the installation went. This ping isn't part of Firefox unified telemetry, it's a bespoke system; we can't use the telemetry client code when it isn't installed yet.
+
+
+Querying the stub ping
+----------------------
+
+The stub ping data is available (to those with a Mozilla LDAP login) on `Redash <https://sql.telemetry.mozilla.org>`_. Make sure to select the ``DSMO-RS`` data source. The ``download_stats`` table is the main data table. It contains the columns in the following list.
+
+Some of the columns are marked [DEPRECATED] because they involve features that were removed when the stub installer was streamlined in Firefox 55. These columns were not removed to keep compatibility and so we could continue to use the old data, but they should no longer be used.
+
+timestamp
+  Time the ping was received
+
+build_channel
+  Channel the installer was built with the branding for ("release", "beta", "nightly", or "default")
+
+update_channel
+  Value of MOZ_UPDATE_CHANNEL for the installer build; should generally be the same as build_channel
+
+version
+  Version number of the installed product, or 0 if the installation failed. This is **not** the version of the installer itself.
+
+build_id
+  Build ID of the installed product, or 0 of the installation failed
+
+locale
+  Locale of the installer and of the installed product, in AB_CD format
+
+amd64_bit_build
+  True if a 64-bit build was selected for installation. This means the OS is 64-bit, the RAM requirement was met, and no third-party software that blocks 64-bit installations was found.
+
+amd64bit_os
+  True if the version of Windows on the machine was 64-bit
+
+os_version
+  Version number of Windows in ``major.minor.build`` format [2]_
+
+service_pack
+  Latest Windows service pack installed on the machine
+
+server_os
+  True if the installed OS is a server version of Windows
+
+admin_user
+  True if the installer was run by a user with administrator privileges (and the UAC prompt was accepted)
+
+default_path
+  [DEPRECATED] True if the default installation path was not changed. We no longer support changing this in the streamlined stub, so this should always be true once `bug 1351697 <https://bugzilla.mozilla.org/show_bug.cgi?id=1351697>`_ is fixed
+
+set_default
+  [DEPRECATED] True if the option to set the new installation as the default browser was left selected. We no longer attempt to change the default browser setting in the streamlined stub, so this should always be false.
+
+new_default
+  [DEPRECATED] True if the new installation was successfully made the default browser. We no longer attempt to change the default browser setting in the streamlined stub, so this should always be false.
+
+old_default
+  True if an existing installation of Firefox was already set as the default browser
+
+had_old_install
+  True if at least one existing installation of Firefox was found on the system prior to this installation
+
+old_version
+  Version of the previously existing Firefox installation, if any
+
+old_build_id
+  Build ID of the previously existing Firefox installation, if any
+
+bytes_downloaded
+  Size of the full installer data that was transferred before the download ended (whether it failed, was canceled, or completed normally)
+
+download_size
+  Expected size of the full installer download according to the HTTP response headers
+
+download_retries
+  Number of times the full installer download was retried or resumed. 10 retries is the maximum.
+
+download_time
+  Number of seconds spent downloading the full installer
+
+download_latency
+  Seconds between sending the full installer download request and receiving the first response data
+
+download_ip
+  IP address of the server the full installer was download from (can be either IPv4 or IPv6)
+
+manual_download
+  True if the user clicked on the button that opens the manual download page. The prompt to do that is shown after the installation fails or is canceled.
+
+intro_time
+  [DEPRECATED] Seconds the user spent on the intro screen. The streamlined stub no longer has this screen, so this should always be 0.
+
+options_time
+  [DEPRECATED] Seconds the user spent on the options screen. The streamlined stub no longer has this screen, so this should always be 0.
+
+download_phase_time
+  Seconds spent in the download phase; should be very close to download_time, since nothing else happens in this phase.
+
+preinstall_time
+  Seconds spent verifying the downloaded full installer and preparing to run it
+
+install_time
+  Seconds the full installer ran for
+
+finish_time
+  Seconds spent waiting for the installed application to launch
+
+succeeded
+  True if a new installation was successfully created. False if that didn't happen for any reason, including when the user closed the installer window.
+
+disk_space_error
+  [DEPRECATED] True if the installation failed because the drive we're trying to install to does not have enough space. The streamlined stub no longer sends a ping in this case, because the installation drive can no longer be selected.
+
+no_write_access
+  [DEPRECATED] True if the installation failed because the user doesn't have permission to write to the path we're trying to install to. The streamlined stub no longer sends a ping in this case, because the installation drive can no longer be selected.
+
+download_cancelled
+  True if the installation failed because the user closed the window during the download.
+
+out_of_retries
+  True if the installation failed because the download had to be retried too many times (currently 10)
+
+file_error
+  True if the installation failed because the downloaded file couldn't be read from
+
+sig_not_trusted
+  True if the installation failed because the signature on the downloaded file wasn't valid and/or wasn't signed by a trusted authority
+
+sig_unexpected
+  True if the installation failed because the signature on the downloaded file didn't have the expected subject and issuer names
+
+install_timeout
+  True if the installation failed because running the full installer timed out. Currently that means it ran for more than 150 seconds for a new installation, or 165 seconds for a paveover installation.
+
+new_launched
+  True if the installation succeeded and we were able to launch the newly installed application.
+
+old_running
+  True if the installation succeeded and we weren't able to launch the newly installed application because a copy of Firefox was already running.
+
+attribution
+  Any attribution data that was included with the installer
+
+profile_cleanup_prompt
+  0: neither profile cleanup prompt was shown
+
+  1: the "reinstall" version of the profile cleanup prompt was shown (no existing installation was found, but the user did have an old Firefox profile)
+
+  2: the "paveover" version of the profile cleanup prompt was shown (an installation of Firefox was already present, but it's an older version)
+
+profile_cleanup_requested
+  True if either profile cleanup prompt was shown and the user accepted the prompt
+
+
+.. [1] No ping is sent if the installer exits early because initial system requirements checks fail.
+.. [2] Previous versions of Windows have used a very small set of build numbers through their entire lifecycle. However, Windows 10 gets a new build number with every major update (about every 6 months), and many more builds have been released on its insider channels. So, to prevent a huge amount of noise, queries using this field should generally filter out the build number and only use the major and minor version numbers to differentiate Windows versions, unless the build number is specifically needed.
new file mode 100644
--- /dev/null
+++ b/browser/installer/windows/docs/index.rst
@@ -0,0 +1,19 @@
+=========
+Installer
+=========
+
+The main role of the Firefox installer is to get a user running Firefox as quickly and reliably as possible, while taking all necessary steps to make Firefox an integrated part of the system.
+
+It turns out that the only platform where we need an installer in order to accomplish all of that is Windows. So we only develop and ship and installer for Windows, and on other platforms we distribute a package in a non-executable format typical of applications distributed on that platform.
+
+Currently, the installers are built on the `NSIS <http://nsis.sourceforge.net/Main_Page>`_ installer framework. This is a Windows-only framework which compiles scripts written in its custom language (along with some native plugins) into an executable installer.
+
+We build two different kinds of installers, the :doc:`Stub Installer <StubInstaller>` and the :doc:`Full Installer <FullInstaller>`. The stub is the default installer intended for most individual users, and the full installer is aimed at power users and administrators who need more control.
+
+There's also a third installer-related program, which is called :doc:`helper.exe <Helper>`. It's also written in NSIS and has a few different jobs that involve maintaining things that the installer sets up, including the uninstaller and a post-update routine.
+
+.. toctree::
+   InstallerBuild
+   StubInstaller
+   FullInstaller
+   Helper
--- a/browser/installer/windows/moz.build
+++ b/browser/installer/windows/moz.build
@@ -4,8 +4,10 @@
 # License, v. 2.0. If a copy of the MPL was not distributed with this
 # file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
 DEFINES['APP_VERSION'] = CONFIG['FIREFOX_VERSION']
 
 DEFINES['MOZ_APP_NAME'] = CONFIG['MOZ_APP_NAME']
 DEFINES['MOZ_APP_DISPLAYNAME'] = CONFIG['MOZ_APP_DISPLAYNAME']
 DEFINES['MOZILLA_VERSION'] = CONFIG['MOZILLA_VERSION']
+
+SPHINX_TREES['installer'] = 'docs'