DOCSEARCHbyAlgolia
Submit Docs

Conveyor

repository·master·Indexed 41 days ago

https://github.com/hydraulic-software/conveyor

A desktop application distribution tool that automates packaging, code signing, and software updates across Windows, macOS, and Linux. It provides specialized integrations for Electron, JVM (including JavaFX and Jetpack Compose Desktop), and Flutter, along with a Gradle plugin and GitHub Action for CI/CD automation.

Tokens
90.9K
Snippets
261
Records
444
Agent score
49%

What's inside Conveyor

  1. Overview of Conveyor features

    master

    Conveyor provides several core capabilities for desktop app distribution:

    • Software Updates: Supports platform-native update systems, Chrome-style silent background updates, web-style synchronous updates on launch, and advanced delta updates.
    • Framework Integration: Specialized support for Electron (generates ASAR files, reads package.json), JVM (bundles optimized jlink JVM and custom native launchers), and Flutter.
    • CI/CD Support: Package and deploy for all platforms from any Linux build agent. Supports automatic releasing to the Microsoft Store, web servers, S3, or GitHub Releases. Includes a dedicated GitHub Action.
    • Code Signing: Sign and notarize apps for every OS from any OS. Supports cloud signing services, HSMs, and generating CSRs.
    • Asset Management: Automatic icon generation, rendering, and format conversion.
    • Distribution: Generates a download page with auto-detection for user OS and CPU architecture.
    • Scaffolding: Can scaffold projects for native C++, Electron, JavaFX (JVM), and Jetpack Compose Desktop (JVM).

  2. Overview of Conveyor

    master
    Conveyor is a tool designed to simplify the distribution of desktop applications. It provides sophisticated software update mechanisms (including delta updates and platform-native package types), deep integration with frameworks like Electron, JVM, and Flutter, and robust CI/CD support. It allows for cross-platform packaging and signing (e.g., signing macOS apps from Linux) and can automatically generate download pages with OS/architecture detection.

  3. Compare Conveyor to Electron autoUpdater

    master

    Conveyor provides several advantages over the standard Electron autoUpdater for packaging and distributing Electron applications:

    • CI/CD Compatibility: Can package, sign, and deploy for all operating systems from any machine (including Linux CI workers) using cloud code signing.
    • Update Styles: Supports both Chrome-style (background, silent) and web-style (immediate on launch, synchronous) updates.
    • Zero App Changes: No modifications to your application's source code are required to enable updates.
    • Delta Updates: Provides excellent support for delta updates automatically.
    • Windows Optimizations:
      • Avoids redundant Electron downloads if the user has existing Electron apps from the MS Store.
      • Network/admin friendly (avoids installing everything into user home directories).
      • Background updates even when the app is not running.
      • Direct deployment to the Microsoft Store.
      • Fast, declarative, interaction-free installs.
    • Infrastructure: No special update servers required; works with static HTTP, S3, or GitHub Releases.
    • Assets: Automatically generates a download HTML page.

  4. What Conveyor does and its core capabilities

    master

    Conveyor is a tool that builds packages for desktop and CLI applications targeting Windows, macOS, and Linux.

    Key capabilities include:

    • Self-updating packages: Uses native package management or Sparkle (on macOS).
    • Cross-platform builds: You can build packages for any OS from any other OS (e.g., sign Mac apps from Linux, or Windows apps from macOS).
    • Signing and Notarization: Handles full signing and notarization for the target platforms.
    • Server Support: Can create simple server packages for Debian/Ubuntu that use systemd as a service manager.
    • Framework Support: Includes built-in features to simplify packaging for Electron, JVM, and Flutter apps.

  5. Use Conveyor open source components

    master

    While the core product is managed by Hydraulic, several key components are available in this repository:

    • The User Guide: Comprehensive documentation for using the tool.
    • The Gradle Plugin: For integrating Conveyor into JVM-based build workflows.
    • GitHub Action: For automating packaging and deployment within GitHub Actions workflows.

  6. Configure JVM applications in Conveyor

    master

    Conveyor provides integrated support for JVM-based applications (Java 11+). It uses a custom launcher to replace the standard java command, utilizes jlink and jdeps to create minimal bundled JVMs, and supports signing native libraries.

    Key features include:

    • Minimal Bundling: Uses jlink to create a slimmed-down runtime.
    • Native Library Support: Dynamic libraries can be signed inside JARs and selectively unpacked based on the target OS/CPU.
    • GUI Framework Support: Integrated support for Jetpack Compose and JavaFX.
    • Build Tool Integration: Gradle plugins for automatic configuration and direct Maven classpath reading.

    Note: Conveyor requires Java 11 or later. Java 8 is not supported.

    # Example of a basic JVM app configuration
include required("/stdlib/jdk/17/openjdk.conf")

app {
  inputs += "build/libs/*.jar"
  jvm {
    gui = com.foobar.Main
  }
}

  7. What is HOCON and how is it used in Conveyor

    master

    HOCON (application/hocon) is the Human Optimized Config Object Notation. It is a superset of JSON used to configure Conveyor. Because it is a JSON superset, all valid JSON is also valid HOCON and will result in the same in-memory data structure.

    Conveyor extends the base HOCON specification with several dynamic features:

    • Brace expansion in string lists.
    • Per-user default files.
    • Environment variable access.
    • External program inclusion: The ability to include the results of external programs to create dynamic configurations computed on the fly.

  8. What is the Conveyor escape hatch and when to use it

    master

    The Conveyor 'escape hatch' is a mechanism that allows you to run an installation repair tool on a user's Windows installation using a channel outside the standard MSIX update mechanism.

    This is necessary when changes to your app would otherwise cause Windows to treat the update as an entirely different application (due to changes in the package family name). Use the escape hatch when you need to:

    • Transition from Conveyor to a different update mechanism.
    • Change your corporate/personal identity (legal name or headquarters location) which affects signing certificates.
    • Switch to a different Certificate Authority (CA).
    • Rebrand the app, including changing the package name.
    • Switch between self-signing and certificate signing.

    Important: You must enable the escape hatch before you actually need it, so that the apps already installed on your users' machines are prepared to check for and execute the repair tool when the change occurs.

  9. Configure machine-specific inputs

    master

    Conveyor uses a hierarchy to define inputs for different target platforms. A machine is identified by a dot-separated triple: os.cpu[.libc].

    Machine Identifiers

    • OS: linux, windows, mac (aliases: win, osx, macos, darwin).
    • CPU: amd64, aarch64 (aliases supported).
    • LibC (Linux only): glibc, muslc (aliases supported).

    Input Hierarchy and Propagation

    Inputs are resolved via app[.jdk].$machine.inputs. Conveyor uses a hierarchical aliasing system where files defined at a higher level propagate to more specific machines. This allows for efficient configuration:

    • app.inputs: Data files used by all machines.
    • app.macos.inputs: Data files used only on macOS.
    • app.macos.aarch64.inputs: Binaries compiled specifically for Apple Silicon (M1/M2/etc).
    • app.linux.amd64.glibc.inputs: Standard Linux inputs.

  10. Use HOCON syntax for conveyor.conf

    master

    The conveyor.conf configuration file uses a syntax that is a superset of JSON, specifically designed for human readability. This allows you to use a more concise dot-notation for nested structures. If you are unsure of the HOCON syntax, you can always use standard raw JSON, as it is fully supported.

    For example, the dot-notation app.foo.bar = 123 is functionally equivalent to the nested object structure app { foo { bar = 123 } }.

    # Dot notation equivalent to nested objects
app.foo.bar = 123

# Nested object syntax
app {
  foo {
    bar = 123
  }
}

  11. Importing Flutter build artifacts

    master

    When configuring app.inputs, provide the paths to the compiled artifacts for each platform.

    macOS Bundle Note

    When importing files on macOS, the root of the inputs is placed inside the app bundle directory. Files should ideally start with Contents/.

    Conveyor automatically detects if a .tar.gz or .zip has a single root directory and will strip it. For example, if your archive contains flutter_demo.app/Contents/..., Conveyor will strip flutter_demo.app/ so that the files correctly start with Contents/ inside the bundle.

  12. Address macOS update limitations

    master

    Due to the Sparkle framework used by Conveyor, macOS applications have specific update behaviors:

    1. No Background Updates: Unlike Windows or Linux (Debian/Ubuntu), the OS will not automatically upgrade the app in the background. The app only updates when it is actively running.
    2. App Translocation: Users must move the application out of their Downloads folder for updates to work. This is a macOS security mechanism. Conveyor uses a modified Sparkle framework to provide clear instructions to the user when this occurs.