Skip to content

Installers

This page documents the native installer pipelines for Windows and macOS, including build scripts, CI workflows, and troubleshooting notes.

Overview

SenoQuant provides native installers for Windows (.exe) and macOS (.pkg) that bundle the application with dedicated Python, OpenJDK, JPype, and scyjava environments.

Both installers follow the same high-level pattern:

  1. Bundle the SenoQuant wheel, micromamba, and launcher scripts.
  2. Run a post-install script on first launch to create the Python environment.
  3. Install OpenJDK, JPype, scyjava, napari, PyTorch, and dependencies.
  4. Launch napari with the SenoQuant plugin.

The Windows package also supports ARM64 hosts by running its existing win-64 environment through Windows 11 x64 emulation. This is an emulated CPU configuration, not a native ARM64 build.

Version management

All installers read the version from pyproject.toml to ensure consistency.

  • Python package: Uses importlib.metadata.version("senoquant") with fallback.
  • macOS installer: Extracts the version using tomllib during build.
  • Windows installer: Reads the version using Inno Setup's ReadIni() function.

To update the version across all installers, edit the version field in pyproject.toml.

macOS installer

Overview

The macOS installer creates a native PKG that installs SenoQuant as an app bundle in ~/Applications/.

The app uses Application Support for writable data so it complies with macOS security policies.

Key components:

  • App bundle: dist/macos-installer/SenoQuant.app.
  • PKG installer: dist/macos-installer/SenoQuant-Installer.pkg.
  • Build script: installer/macos/build_macos_installer.sh.
  • Launcher: installer/macos/launch_senoquant.sh.
  • Post-install: installer/macos/post_install.sh.
  • Environment config: installer/macos/environment.macos.yml.

Build pipeline

The installer is built via .github/workflows/macos-installer.yml:

  1. Build the SenoQuant wheel.
  2. Download micromamba for Apple Silicon macOS.
  3. Convert the SVG icon to ICNS format using librsvg.
  4. Assemble the app bundle with launcher scripts and resources.
  5. Create a component PKG with bundle relocation disabled.
  6. Package into a product PKG installer.

Local build commands

Prerequisites:

  • macOS 10.15 or later.
  • Python 3.11 or later.
  • Build tools: python -m pip install build.
  • Icon converter (recommended): brew install librsvg.

From the repository root:

bash installer/macos/build_macos_installer.sh

The resulting PKG is written to dist/macos-installer/SenoQuant-Installer.pkg.

App bundle structure

SenoQuant.app/
  Contents/
    Info.plist
    MacOS/
      launch_senoquant.sh
    Resources/
      senoquant.icns
      post_install.sh
      environment.macos.yml
      tools/
        micromamba
        osx-arm64/micromamba
      wheels/
        senoquant-*.whl

Installation flow

  1. The user runs the PKG, which installs to ~/Applications/SenoQuant.app.
  2. The user launches the app, which runs launch_senoquant.sh.
  3. If launched from Finder, the launcher opens Terminal so logs are visible.
  4. If ~/Library/Application Support/SenoQuant/env does not exist, the launcher runs post-install.
  5. Post-install creates the Python/OpenJDK/JPype/scyjava environment and installs dependencies.
  6. The launcher starts napari with the SenoQuant plugin.

Writable data locations

To avoid self-modification inside ~/Applications, SenoQuant writes runtime data to Application Support:

  • Python/OpenJDK/JPype/scyjava environment: ~/Library/Application Support/SenoQuant/env.
  • Launch log: ~/Library/Application Support/SenoQuant/launch.log.
  • Post-install log: ~/Library/Application Support/SenoQuant/post_install.log.

The app bundle at ~/Applications/SenoQuant.app remains read-only after installation.

PKG configuration details

Install location:

  • Component payload path: /Applications.
  • Product install domain: CurrentUserHomeDirectory (so app installs to ~/Applications).

Component plist settings:

  • BundleIsRelocatable: false, which prevents macOS from moving the app.
  • BundleOverwriteAction: upgrade, which allows reinstallation.

The build uses a staging directory (pkg_staging/) with SenoQuant.app at the payload root so pkgbuild --install-location /Applications produces ~/Applications/SenoQuant.app.

Architecture support

The macOS installer targets Apple Silicon (arm64) and uses ARM64 micromamba.

PyTorch is installed from standard channels and includes MPS support on Apple Silicon.

Troubleshooting

Icon not appearing.

  • Install librsvg: brew install librsvg.
  • Rebuild the installer.
  • Alternatively, place senoquant.icns manually in Resources/.

App does not launch.

  • Check ~/Library/Application Support/SenoQuant/launch.log.
  • Check ~/Library/Application Support/SenoQuant/post_install.log.
  • Verify micromamba exists at ~/Applications/SenoQuant.app/Contents/Resources/tools/micromamba.

Terminal window does not open.

  • The app uses AppleScript to open Terminal when launched from Finder.
  • Try launching directly from Terminal using ~/Applications/SenoQuant.app/Contents/MacOS/launch_senoquant.sh.

Permission denied errors.

  • Verify launch_senoquant.sh and post_install.sh are using the Application Support path.

Windows installer

Overview

The Windows installer bundles a portable app directory and runs a post-install step to create the Python environment, install dependencies, and install the SenoQuant wheel.

Key components:

  • App bundle root: dist/windows-installer/senoquant.
  • Inno Setup script: installer/windows/senoquant.iss.
  • Build script: installer/windows/build_windows_installer.ps1.
  • Post-install script: installer/windows/post_install.ps1.
  • Platform detection helper: installer/windows/platform.ps1.
  • Uninstall cleanup helper: installer/windows/uninstall.ps1.

Build pipeline

The installer is built via .github/workflows/windows-installer.yml:

  1. Build the SenoQuant wheel into the app bundle.
  2. Download and include micromamba.exe.
  3. Copy launchers, icons, and post-install scripts into the bundle.
  4. Package with Inno Setup into SenoQuant-Installer.exe.

Local build commands

Prerequisites:

  • Python 3.11.
  • Inno Setup (ISCC).
  • ImageMagick (magick on PATH).

From the repository root:

  1. Build the app bundle.
.\installer\windows\build_windows_installer.ps1
  1. Build the installer with Inno Setup.
$iscc = "${env:ProgramFiles(x86)}\Inno Setup 6\ISCC.exe"
& $iscc .\installer\windows\senoquant.iss

The resulting installer is written to installer/windows/Output/SenoQuant-Installer.exe.

App bundle layout

The build script assembles this structure under dist/windows-installer/senoquant:

senoquant/
  .senoquant-managed-install
  launch_senoquant.bat
  launch_senoquant.ps1
  platform.ps1
  post_install.ps1
  uninstall.ps1
  senoquant_icon.ico
  tools/
    micromamba.exe
  wheels/
    senoquant-*.whl

Post-install steps

post_install.ps1 runs after installation to:

  • Create a Python 3.11, OpenJDK 21, JPype, and scyjava environment under env/.
  • Install napari[all] and SenoQuant from the local wheel.
  • Install PyTorch 2.5.1 with CUDA 12.1 on x64 Windows or CPU-only PyTorch on a Windows ARM64 host.
  • Set JAVA_HOME to the bundled environment so BioFormats/scyjava does not depend on system Java.
  • Run uv installs with --system-certs and clear SSL_CERT_FILE / SSL_CERT_DIR inside the micromamba child process so enterprise proxy trust uses the OS certificate store.
  • Validate imports.

The SenoQuant wheel pulls in runtime dependencies, including senoquant-stardist-ext.

The native launcher sets SENOQUANT_MODEL_DIR to env/models/. Hugging Face downloads models there when they are first used instead of writing inside the installed Python package. Because the cache is part of the managed environment, application upgrades and uninstall cleanup remove it with env/.

Windows architecture behavior

The Inno Setup package uses ArchitecturesAllowed=x64compatible, which permits the x64 application payload on both x64 Windows and ARM64 Windows 11. The bundled micromamba executable and environment remain win-64 in both cases.

During post-install, platform.ps1 checks the process and operating-system architecture indicators. On an ARM64 host, setup:

  1. Requires Windows 11 24H2 (build 26100) or later.
  2. Creates the same win-64 Python 3.11 environment used on x64 Windows.
  3. Installs CPU PyTorch instead of the CUDA 12.1 build.
  4. Validates that Python is running as x64, CUDA is unavailable, and ONNX Runtime exposes its CPU execution provider.

This retains the normal SenoQuant feature surface, including StarDist's x64 extension, but inference runs on the CPU through Windows x64 emulation. Native ARM64 wheels, CUDA, and NPU execution are outside the current support scope.

Uninstall behavior

Inno Setup registers SenoQuant in Windows Installed Apps. Before uninstalling, it runs uninstall.ps1 -CheckOnly and stops if a Python process from the managed environment is active. During uninstall, the helper removes the generated env/ directory, including its model cache, plus installed_version and post_install.log; Inno Setup then removes the files it originally installed. Version upgrades rebuild env/, so models are downloaded again on first use after an upgrade.

Recursive cleanup requires the .senoquant-managed-install ownership marker and refuses linked or redirected env/ directories. The helper never recursively removes the application root, so unrelated files in a custom install directory are preserved. User-selected datasets, exports, settings outside the install directory, and shared external caches are also outside the uninstall surface.

Troubleshooting

Missing StarDist ops.

  • Verify senoquant-stardist-ext is installed.
  • Check compiled binaries under env/Lib/site-packages/senoquant/tabs/segmentation/stardist_onnx_utils/_stardist/lib/.

Install location issues.

  • Avoid Program Files to reduce permissions issues.
  • Prefer user-local install paths, such as %LOCALAPPDATA%.

GPU not detected.

  • Windows ARM64 intentionally uses CPU inference and does not expose CUDA.
  • Verify that a current NVIDIA driver is installed with nvidia-smi.
  • Check PyTorch with python -c "import torch; print(torch.cuda.is_available(), torch.version.cuda)".
  • Confirm the installer pulled PyTorch 2.5.1 with its CUDA 12.1 runtime. A separate CUDA Toolkit installation is not required for the packaged application.

CI/CD workflows

Both installers are built automatically via GitHub Actions:

  • macOS: .github/workflows/macos-installer.yml.
  • Windows: .github/workflows/windows-installer.yml.

Triggers:

  • Manual dispatch via workflow_dispatch.
  • Automatic runs on release publication.

Artifacts:

  • Uploaded as build artifacts for testing.
  • Automatically attached to GitHub releases.

Verification:

  • macOS: pkgutil --check-signature (unsigned PKG).
  • Windows: successful Inno Setup build (signing is not configured by default).