Skip to content

Distributing

Jump to bottom
Tres Finocchiaro edited this page Jan 2, 2026 · 24 revisions

Create a QZ Tray distribution

This assumes Windows signing and macOS package signing have been configured.

Update the version

  • src/qz/common/Constants.java
  • js/qz-tray.js (two places)
  • js/package.json (for npm)

Before publishing make sure to commit the above version changes. We usually just call this Bump version.

Create the builds

Chain all three builds on macOS, following compiling tutorial.

ant pkgbuild && cp out/*.pkg ~/Desktop/ && \
ant makeself && cp out/*.run ~/Desktop/ && \
ant -Dtarget.arch=x86_64 nsis && cp out/*.exe ~/Desktop/ && \
ant -Dtarget.arch=x86_64 pkgbuild && cp out/*.pkg ~/Desktop/ && \
ant -Dtarget.arch=x86_64 makeself && cp out/*.run ~/Desktop/ && \
ant -Djlink.java.version=21.0.7+9 -Dtarget.arch=riscv64 makeself && cp out/*.run ~/Desktop && \ 
echo "Done"

Sign Windows Release

As of QZ Tray 2.2.5, this is done automatically by the build system using Amazon KMS

Click to expand old steps

Sign the .exe using DigiCert EV cert on Windows. Note, if you're on a High DPI screen, the app might look weird. Use this regkey and manifest to fix it.

  • Insert the USB hardware key (if it's not ready, read this first)
  • Download the DigiCertUtil.exe
  • Wait for Windows to setup the hardware key (about 5 minutes)
  • If it's the first time using the key on this computer, click "Repair cert"
  • Sign using SHA1, then SHA2
    • When prompted for a password, Windows 10 may ask for a PIN, but actually use the full hardware password.

Notarize macOS Release

  • Send the package to Apple for notarization:

       xcrun notarytool submit --wait qz-tray-x.x.x-arm64.pkg --wait --apple-id <developer-id>@qz.io --password <the-secure-password> --team-id <team-id>
    • apple-id: The email of the apple developer account
    • password: The application-specific password (NOT the Apple developer password!)
    • team-id: The signing ID, e.g. P5DMU6659X

  • After a few minutes, it returns:

    Processing complete
   id: abcdefgh-abcd-1234-abcd-abcdefghij
+  status: Accepted

  • Which then can be monitored remotely using:

    xcrun notarytool log abcdefgh-abcd-1234-abcd-abcdefghij --apple-id <developer-id>@qz.io --password <the-secure-password> --team-id <team-id>

  • Finally, staple the installer:

    xcrun stapler staple qz-tray-x.x.x-arm64.pkg
    Processing: qz-tray-x.x.x-arm64.pkg
Processing: qz-tray-x.x.x-arm64.pkg
+ The staple and validate action worked!

Publish

  • Upload builds to https://github.com/qzind/tray/releases/new

    • Tag: v2.x.x (remember the v)
    • Name: 2.x.x

  • Create simple, effective release notes. e.g.

    **201X-01-01**

**Features**

* CP-987 support (#954)

**Fixes**

* Fixes HTTPS connections (#956)
* Better signing example for js (a1b2c3d)

  • Email premium clients (qz.io (slash) admin)

    • Include abridged version of release notes
    • Link to download
    • Provide any additional information (such as status of 2.x.x beta)

  • Post to Facebook, Twitter

  • Update npm Assumes npm is installed (e.g. brew install npm)

    • Open a terminal to js (e.g. ~/tray/js)
    • Ensure package.json version is up to date
    • If not already, call npm adduser
      • User: qzind
      • Public Email: support@qz.io
    • Finally, call npm publish

Advanced

Custom Provisioning

For custom provisioning options (such as bundling software, scripts, properties, etc), see provisioning

Bundling a custom Java Runtime

In some cases, a custom Java Runtime (JRE/JDK) is desired. QZ Tray can be built against the following Java Runtimes:

  • BellSoft Liberica (default)
  • Eclipse Adoptium
  • IBM Semeru
  • Microsoft OpenJDK
  • Amazon Coretto
  • Azul Zulu

To specify a runtime, provide it at build-time as jlink.java.vendor

ant -Djlink.java.vendor=Eclipse makeself # Use Eclipse Adoptium

(Note: jlink.java.gc and/or jlink.java.gc.version may be needed for IBM Semeru)

Bundling a local Java Runtime

When testing a patched JDK, a one-off, local runtime is often needed.

  1. Download the custom runtime image (usually in .zip format)

  2. Extract the runtime (e.g. ~/Downloads/jdk-25.0.1.jdk)

    • If on macOS, ensure to remove the quarantine flags from the runtime 
      sudo xattr -d -r com.apple.quarantine ~/Downloads/jdk-*

  3. Provide this runtime image to ant/jlink:

    ant -Djlink.java.target=$HOME/Downloads/jdk-25.0.1.jdk makeself # ... or pkgbuild, nsis, etc

  4. If major versions differ (e.g. 11 vs 25), you may also provide -Djlink.java.version=25

Clone this wiki locally