Skip to content

Dplug Installer Guide

Jump to bottom
p0nce edited this page Feb 1, 2024 · 50 revisions

Making a Windows or Mac installer is supported by calling dplug-build with the --installer flag in a single command-line call.

Example:

# Build all those formats, in 64-bit and 32-bit, bundles in an installer.
dplug-build -a all --final -c VST2-FULL -c VST3-FULL --installer

  • macOS: This creates a .pkg file on macOS with all selected artifacts.
    For Mac you will need to notarize that installer next, but first follow this Guide.

  • Windows: This creates a .exe NSIS installer on Windows.

  • Linux: No --installer support.

Windows installer

What dplug-build --installer does

Using the --installer flag in dplug-build performs the following actions:

  • Generates a NSIS script, then execute it
  • Uses signtool from the Windows SDK to sign the resulting .exe

Requirements

  • You'll need a dplug-build built from the Dplug version you use in your plug-in.
  • Everything is signed with timestamps, so you can optionally sign your installer (recommended).
  • Windows 10 SDK must be installed
  • Must append path to signtool.exe to PATH variable
  • NSIS must be installed (download it here => https://nsis.sourceforge.io/Main_Page)
  • Must append path to makensis.exe to PATH variable

plugin.json additions

The windows installer uses the following fields in plugin.json

--- plugin.json ---
"windowsInstallerHeaderBmp": "../path/to/header.bmp",

Optional 150 x 57 pixels BMP image to use in the installer. That header image has special requirements. 🎉

  • Either exported with MSPaint as a .bmp
  • Or exported as a 24-bit (or 8-bit indexed) .bmp with GIMP, without colorspace information (see Compatibility options).
  • Preferably in a "pixel art" style.
    In non-100% DPI, the header image will get resized with nearest-neighbour sampling by the installer.
    There is no known fix unfortunately.

Choice A: Code-signing with a private .p12 key file (eg: Sectigo)

--- plugin.json ---
"keyFile-windows": "../path/to/cert.p12",

Path to PFX/.p12 keyfile.

--- plugin.json ---
"keyPassword-windows": "p3ssW0rd",

Password for PFX/.p12 keyfile. Use an $ENVVAR here. Can be the special value "!PROMPT" for security.

--- plugin.json ---
"keyPassword-windows": "$MY_CERT_PASSWORD",

Choice B: Code-signing with a cloud signing method (eg: Certum)

--- plugin.json ---
"developerIdentity-windows": "name of certificate",

This is the name of the certificate in your certmgr.msc. When present, this overrides "keyFile-windows" which is then unused.

Timestamp server

It is vital to timestamp your codesigned executable. The timestamp is itself signed by a certificate authority, and as such you can choose the server URL.

--- plugin.json ---
"timestampServerURL-windows": "url of RFC3161 timestamp server",

Timestamps are always used, that key is only useful to override the default timestamp server URL.

Mac installer

What dplug-build --installer does

  • on MacOS when dplug-build gets the --installer switch, it gathers all things built (except intermediate artifacts) from the same command-line invocation into a merged package. This package is named build/<pluginname>-<configuration-suffix>-<version>.pkg.
  • this configuration suffix is taken from the configuration name. If the configuration is named VST2-SILVER-EDITION then the configuration-suffix is SILVER-EDITION. Such a suffix need not exist.
  • dplug-build will create an intermediate .pkg for each build, those cannot be distributed: they lack a licence and a background file.
  • bundle, intermediate .pkg and final .pkg all get codesigned with codesign, pkbbuild and productbuild respectively.

Requirements

  • Be sure to have Xcode 12.2 or superior.
  • You'll need a dplug-build built from the Dplug version you use in your plug-in.
  • the Mac installer may have an optional PNG background, dplug-build will help with the new plugin.json key:
--- plugin.json ---
"installerPNGPath": "../installer-background.png",
  • You'll need to convert license.txt into a license.md, dplug-build will warn about that too:
--- plugin.json ---
"licensePath": "../license.md",
  • You'll need to be a registered Apple developer in the Apple developer program, and install 2 Apple certificate (one for "3rd party Developer Installer" and the other for "3rd party Developper application"). dplug-build will help filling the new plugin.json entry:
--- plugin.json ---
"developerIdentity-osx": "XXXXXXXXXX",

Pro-tip: Do a .p12 backup of your "Developer ID Application" and "Developer ID Installer" certificates. Open Keychain Access application, and right-clicking on a certificate to create a .p12 file. Because Apple limits the number of certificates you can generate.

Example

A dplug-build invocation for a final installer could simply be:

$ dplug-build -c AU-FULL -c VST-FULL -c VST3-FULL --final --installer --notarize

This command-line will build an optimized 64-bit distributable plug-in for all the configurations in that same command-line, and will notarize the result.

The recommended way to distribute this .pkg file is either direct download or bundling them in a ZIP file, which doesn't have to be signed itself. GateKeeper may still warn about the developer being unregistered for the first downloads: the exact mechanics is opaque.

Finally!

You now have your own plug-in macOS installer. The next thing you'll need is to notarize it.
A fun and passionating quest begins.

Clone this wiki locally