DHIVA LABS · LEARN

Appearance

Build a Windows installer ​

winbridge package turns the files from winbridge build into a single Windows setup program. This page covers the default installer, your own installer script, and signing.

What the installer does ​

An installer is the setup.exe a Windows user double-clicks. The one WinBridge generates:

  • installs your app into Program Files,
  • adds a Start Menu shortcut,
  • adds an entry under Add or Remove Programs,
  • includes an uninstaller.

WinBridge builds it with NSIS, a widely used open-source installer system. NSIS is a Windows program, so WinBridge runs it under the same managed Wine runtime that winbridge run uses. You install neither yourself: both are downloaded on first use (NSIS is 2 MB, the Wine runtime about 94 MB).

Build an installer ​

  1. Build the project first.

    bash
    winbridge build ./myapp

  2. Package it, giving the version number to record in the installer.

    bash
    winbridge package ./myapp --app-version 1.2.3

  3. Find the installer next to the build output: myapp/build/winbridge/windows-x64/myapp-1.2.3-setup.exe.

Every file directly in the build output folder goes into the installer, except installers and .nsi scripts left by earlier packaging runs. Subfolders are not included. The Start Menu shortcut points at the .exe named after the project; if there is none with that name, it points at the first .exe by name.

Without --app-version, the version is 0.0.0.

Good to know

The setup program itself is a 32-bit Windows executable, so it starts on any Windows version whatever the app inside it is. That is NSIS's normal behaviour.

Options ​

OptionWhat it doesDefault
--artifactsFolder that holds the built files.build/winbridge/windows-x64 in the project
-o, --outputInstaller file to write.<app>-<version>-setup.exe in the artifacts folder
--app-versionVersion recorded in the installer.0.0.0
--scriptYour own NSIS script, used instead of the generated one.None
--signA PKCS#12 certificate (.pfx) to sign the installer with.None

Use your own installer script ​

WinBridge writes the NSIS script it generates next to the build output on every run. To change what the installer does, copy that .nsi file somewhere else, edit the copy, and pass it with --script:

bash
winbridge package ./myapp --script installer/myapp.nsi -o dist/setup.exe

Edit a copy, not the generated file: WinBridge overwrites the generated one each time.

Sign the installer ​

Windows warns users about programs from an unknown publisher. Authenticode signing attaches your publisher identity to the installer with a code-signing certificate, which you obtain from a certificate authority.

  1. Install osslsigncode. WinBridge does not download it. On Debian and Ubuntu:

    bash
    sudo apt install osslsigncode

  2. Put the certificate passphrase in the WINBRIDGE_SIGN_PASSPHRASE environment variable. Typing read -rs first keeps it off the screen and out of your shell history:

    bash
    read -rs WINBRIDGE_SIGN_PASSPHRASE
export WINBRIDGE_SIGN_PASSPHRASE

  3. Package with --sign and the path to your .pfx file.

    bash
    winbridge package ./myapp --app-version 1.2.3 --sign certs/app.pfx

If the variable is not set, osslsigncode asks for the passphrase itself. There is no command-line option for the passphrase, on purpose: anything on a command line can be read by other processes on the machine.

Signatures are timestamped through a public timestamp server, so they stay valid after the certificate expires. Signing therefore needs an internet connection.

If osslsigncode is missing, --sign fails with a message saying so. WinBridge does not leave you with an installer you believe is signed when it is not.

DANGER

A .pfx file and its passphrase are your publisher identity. Keep the certificate out of your source repository and never put the passphrase in a script that is committed or shared.

Limits ​

  • Installers are NSIS .exe files. MSI packages are not supported.
  • The generated installer packs only the files at the top of the build output folder. An app that needs subfolders, such as the data folder of a Flutter app, needs your own NSIS script.
  • The WinBridge project's tests cover how the signing command is built, not signing against a real certificate authority. Check the signature on Windows (file Properties, Digital Signatures tab) before you publish.

Next steps ​