Skip to content

Latest commit

 

History

History
104 lines (69 loc) · 10.2 KB

cross-platform-packaging.md

File metadata and controls

104 lines (69 loc) · 10.2 KB

Packaging for Windows, macOS, and Linux

English | 简体中文

The host builds and packages independently, using a standard backend JAR and matching native runtime materials. Build external plugins separately and explicitly bundle them with --plugins-dir. Packaging mode, platform, package type, and signing are selected independently. The production license service is https://update.opentest.com; there is no separate test server.

Common Shortcuts

These five commands select a fixed platform, mode, and artifact type without additional arguments:

Purpose Command Publisher signing
Windows test mode installer pnpm package:windows:installer:test None
Windows test mode upgrade pnpm package:windows:upgrade:test None
Windows production installer and upgrade pnpm package:windows:both:prod:signed Yes; explicitly bundled plugins also undergo native-signature verification
Mac test mode installer pnpm package:mac:installer:test None; retains ad-hoc signatures
Mac production installer pnpm package:mac:installer:prod None by default; retains ad-hoc signatures; add --sign for publisher signing

For a Mac production package with Developer ID signing and notarization, run pnpm package:mac:installer:prod --sign --notarize. Notarization uploads artifacts to Apple. Each shortcut accepts --config <file> and --check. These are the five retained shortcuts; other combinations, including Linux, use the shared pnpm package entry point.

Commands and Artifacts

Run from the host root in a native terminal on the target operating system. Windows cannot cross-build Mac/Linux desktop native modules.

Entry point Architecture --kind installer --kind upgrade --kind both
pnpm package --platform windows x64 NSIS EXE Complete upgrade EXE + latest.yml Both
pnpm package --platform mac arm64 DMG ZIP + latest-mac.yml Both
pnpm package --platform linux x64 DEB TAR.GZ for manual replacement Both
pnpm package --platform windows --mode production --kind both --sign
pnpm package --platform mac --mode production --kind installer
pnpm package --platform mac --mode production --kind both --sign
pnpm package --platform linux --mode production --kind both

Omitted arguments default to --mode test --kind installer, without publisher signing. Production examples explicitly use --mode production. Both modes connect to the same production service and differ only in local configuration and native materials. Use pnpm package --platform windows|mac|linux; an omitted platform defaults to the current system. Other combinations use explicit arguments. --arch accepts only the architectures in the table; Mac x64, Linux arm64, and universal materials are not available.

Linux uses DEB/TAR.GZ without electron-updater metadata, and in-app automatic updates are disabled. Upgrade an installed DEB through the system package manager using a new DEB. TAR.GZ supports manual replacement of a standalone extracted directory after application exit; do not overwrite files managed by DEB. Linux explicitly rejects --sign, since there is no DEB/TAR publisher-signing workflow.

Output resides in dist/releases/<platform>-<arch>/<mode>/<signed|unsigned>/<installer|upgrade>/. Only after all requested targets succeed is a sibling delivery.json written, recording platform, architecture, mode, signing, notarization, and artifact digests. Only selected directories are cleared. Both package types reuse host compilation, native staging, Java runtime, and the prepared application. The second container uses prepackaged without signing or notarizing a Mac App again. Explicitly bundled plugins use independently built final packages.

Build Requirements

  • Use existing Node, pnpm, Maven, a full JDK 21, and installed locked dependencies. Commands do not install base tools or project dependencies.
  • Windows uses MSVC/Windows SDK and vendor/java/windows-x64.
  • Mac requires ARM64 Node, Xcode Command Line Tools, CMake >=3.20, and Python 3. Packaging uses system codesign; notarization additionally needs xcrun notarytool/stapler.
  • Linux requires x64 Node, a C++17 compiler, make, CMake >=3.20, Python 3, and the PulseAudio/hidapi headers and libraries required by the current CMake configuration. Installed systems need runtime dependencies declared by DEB, including GTK, NSS, ALSA, PulseAudio, udev, and OpenSSL. TAR.GZ does not install these automatically.
  • pnpm deps:check checks base tools for the current platform, without covering all native development packages or hardware acceptance.
  • Mac/Linux use jlink from JAVA_HOME to produce a compact Java 21 runtime, including the required Java SE, EC cryptography, ZIP, character-set, and localization modules. OPENTEST_MAC_JDK and OPENTEST_LINUX_JDK override the distribution JDK without changing Maven's development JDK.

platforms.windows/mac/linux in packaging.config.json supplies platform-specific paths. Each file applies common, platform, mode, then platform-specific mode configuration; --config applies the same hierarchy afterward. Paths resolve relative to the file defining them. For example:

{
  "platforms": {
    "mac": { "javaJdk": "/Library/Java/JavaVirtualMachines/jdk-21.jdk/Contents/Home" },
    "linux": { "javaJdk": "/opt/jdk-21" }
  }
}

A platform's javaRuntime can instead point to a prepared Java 21 runtime directory for that system, skipping jlink. Validation checks the version, OS_NAME, and OS_ARCH in release. See Development and Packaging for local configuration, the license service, and optional plugin integration.

Native Materials and Runtime Integration

Native inputs come from native/windows-amd64, native/macos-arm64, and native/linux-amd64. Production packages apply the selected platform's prd overrides only in staging, without overwriting source binaries.

Mac/Linux packaging copies and checks precompiled Java Native Interface (JNI) libraries, the OptDevHost device host, and algorithm libraries. JNI libraries must contain the current com.opentest namespace and prepareManagedRuntime interface. Missing or outdated materials stop packaging; supply compatible versions first. This workflow does not compile JNI, the device host, or vendor SDKs; it uses the precompiled binaries. Bundled device materials require explicit configuration. Device plugin compatibility with host binary interfaces and protocols must still be tested on target machines.

Desktop Node native extensions are still built for the target platform and use dlopen/dlsym to load .dylib / .so. This is separate from preparing precompiled backend JNI materials. Windows retains its loading implementation. Production desktop and backend components use the same production analysis library.

Installed data roots are %LOCALAPPDATA%/OpenTest on Windows, ~/Library/Application Support/OpenTest on Mac, and ${XDG_DATA_HOME:-~/.local/share}/OpenTest on Linux. Existing explicit runtime directory overrides remain supported. Mac/Linux run writable native materials under the user data root's native/, preserving device plugin edits, removals, and state. Core materials refresh from installed content without modifying the signed App or system installation. JNI working directories also reside under user runtime storage. Mac startup retains Netty's option preventing signed JNI rewriting and requests microphone permission when no decision has been made.

Mac Signing and Notarization

Without --sign, Apple ARM64 still receives the ad-hoc signatures required to run. These are not Developer ID publisher signatures, and output remains under unsigned.

Before using --sign, configure a Developer ID Application identity with its private key in the Mac keychain and set:

export OPENTEST_MAC_SIGN_IDENTITY='Developer ID Application: Your Company (TEAMID1234)'
export OPENTEST_MAC_TEAM_ID='TEAMID1234'
pnpm package --platform mac --mode production --kind both --sign

Alternatively set the platform's signing.identity and signing.team. Host signing covers the App, Electron helpers, Java/JNI, and Mach-O files inside host backend JARs. The plugin repository's shared packaging tools apply matching ad-hoc or Developer ID signatures to bundled .otplugin Mach-O files and generate final digests. The host validates and uses final packages unchanged, without re-signing or rewriting digests or indexes. No publisher signatures are added to Java classes or plugin envelopes. Unicode filename normalization, Hardened Runtime, Java/Electron entitlements, and installed-copy signature verification remain in effect.

Notarization is separate from signing. Uploads to Apple occur only with an explicit --notarize:

export OPENTEST_NOTARY_PROFILE='OpenTest-Notarization'
pnpm package --platform mac --mode production --kind both --sign --notarize

Maintainers store credentials in the keychain beforehand. The sequence is: sign App, submit and wait for Accepted, staple App, generate final ZIP/DMG, sign DMG, notarize and staple DMG. ZIP update digests are generated after the App is final. DMG does not emit update metadata that later signatures could invalidate. Failure at any step prevents a complete delivery record. A Developer ID package without --notarize is not notarized and cannot be treated as having passed Gatekeeper distribution acceptance. The separate pnpm notarize:mac tool remains available. Manual artifact changes require new digests rather than reuse of an old delivery.json.

Verification Limits

--check reads and validates the build system, materials, and selected signing requirements without compiling C++ or proving JNI ABI or device compatibility. Tool tests validate actual electron-builder 25.1.8 configuration and cover platform settings, jlink arguments, signing order, plugin archive digests, and output isolation.

On each target platform, check native materials, backend startup and JNI interfaces, installation startup, installed plugin registration and restart, upgrade data retention, and real device acquisition. When signing or notarization is required, also validate actual artifact signatures and distribution behavior. Tool tests or successful packaging cannot replace these checks.