NSIS Rules for Bazel

Contents

1. Overview
   1. Usage
   2. Features
2. Generated Installer Details

Overview

Adds rules for creating NSIS installers for bazel.

This project was originally inspired by CPack, but design and approach has since started to diverged.

Usage

bazel_dep(name = "rules_nsis", version = "<version>")

nsis = use_extension("@rules_nsis//nsis:extensions.bzl", "nsis")
# Currently 3.11 is the only supported version.
nsis.executable(name = "nsis", version = "3.11")

use_repo(nsis, "nsis_tool", "nsis_toolchains")

register_toolchains("@nsis_toolchains//:all")

Define Installer

For a full list of options, see: https://registry.bazel.build/docs/rules_nsis

For installer examples, see the tests: ./tests/BUILD.bazel.

load("//nsis:defs.bzl", "nsis_component", "nsis_component_group", "nsis_installer")

nsis_component(
    name = "my_minimal_component",
    srcs = [":my_files"],
    selection_mode = "default",
)

nsis_component_group(
    name = "my_minimal_group",
    components = [
        ":my_minimal_component"
    ],
)

nsis_installer(
    name = "my_minimal_installer",
    components = [
        ":my_minimal_group",
        ":my_minimal_component",
    ],
    product = "My Minimal Product",
    product_path = "My Minimal Product",
)

Features

• NSIS Toolchain for cross-platform use.
• Define installer attributes (version, product, etc.).
• Support Components and Component Groups.
• Install windows Services (uses sc.exe).
• Dependency Based Selections.
• Handle Stamping Installers
• EventLog Registry Entries
• Uninstall previous installs prior to install
• StartMenu Entries. [Help Wanted]
• Desktop Shortcuts. [Help Wanted]
• Update Path. [Help Wanted]
• Set Environment Variables. [Help Wanted]
• Don't prompt for components if all hidden or all required.
• Enable adding files directly to installer (add to hidden section).

Generated Installer Details

• Unicode
• Uninstaller file name: Uninstaller.exe
• Writes to Windows Registry Software\{{.Product}} or Software\{{.Vendor}}\{{.Product}} depending on what values are provided. Writes to subkeys:
  • InstallDir
• Adds uninstaller details to Software\Microsoft\Windows\CurrentVersion\Uninstall\{{.Id}} writes to the same package path as above. Writes to subkeys:
  • DisplayName
  • DisplayVersion
  • Publisher
  • UninstallString
  • NoRepair = 1 (Repair not supported)
  • NoModify = 1 (Modify not supported)
  • DisplayIcon
• Writes to 32 or 64 registry depending on arch selected.
• Asserts that the installer is being run on the correct architecture based on provided arch.
• By default will allow 32bit installers to be installed on 64bit systems. This can be disabled.
• Uses MUI for the UI.
• Logs to StdOut if run from a console.
• Ensures only one installer is running using a mutex.
• Uninstalls previous installs when run.
• Installs and updates windows services using sc.exe
  • Will always attempt to stop the service before component section runs.
  • All component files are updated before the service is updated or created.
• When /TESTID={{.TestId}} is passed, will append TestId to the registry keys it uses. This is to handle race conditions while testing installers.
• If version is not provided, will default to 0.0.0.0.
• EventLog keys written to SYSTEM\CurrentControlSet\Services\EventLog\Application\{{.Id}}

Stamping

• Stamp values will be substituted with their workspace avlues when built with stamping.
• If build or installer is not stamped, stamp templates will be substituted using stamp_defaults if provided, otherwise, will default to the empty string.
• Vendor and Product can be stamped, but it is not recommended since it can result in odd or broken behavior (however, its behavior is well defined below).
  • Output file name will not include stamped information unless stamp_defaults has a value for it. Because information gets removed, it can lead to unintentional file name clashes.
  • If you need these fields to be configurable, or want to follow DRY (Don't Repeat Yourself), it is recommended to use variables or configurable attributes.

Component Dependencies

Based on dependencies provided in each component, a dependency graph between components is created and then embeded in the installer. In the component selection screen the following behavior will be seen:

1. When a component is selected, all of its dependencies (including transitive dependencies) will also be selected.
2. When a component is unselected, the all of its dependencies (including transitive dependencies) will be unselected, unless:
   1. They were selected manually.
   2. They are dependend on by another component (either directly or transitively).
3. When a component is unselected, all dependents (either direct or transitive) will be unselected (even if they were selected manually).