Skip to content

About

Build MATLAB once on a licensed Linux runner and package native Windows, Linux, and macOS releases without a batch licensing token.

Topics

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Cross-platform MATLAB releases without a batch licensing token

Validate template

Build MATLAB code once on a licensed self-hosted Linux runner, then package native application bundles for Windows, Linux, and macOS with GitHub-hosted runners.

No MLM_LICENSE_TOKEN is used. MATLAB is not installed on the Windows or macOS jobs.

The problem

The official matlab-actions/setup-matlab route is convenient until a workflow is private or uses a transformation product such as MATLAB Compiler. Those cases require a MATLAB batch licensing token obtained through the Batch Licensing Pilot. Batch licensing also does not support external-language interfaces, for which MathWorks recommends a normally licensed self-hosted runner.

That makes a conventional three-OS MATLAB build matrix awkward:

  • three operating systems need MATLAB setup;
  • MATLAB Compiler licensing must work in ephemeral CI jobs;
  • the batch token is not a normal license key and is not always available;
  • each platform repeats an expensive compilation.

If you already have an activated Linux machine with MATLAB, MATLAB Compiler, and MATLAB Compiler SDK, there is a much simpler split.

The solution

flowchart LR
    A[MATLAB source] --> B[Self-hosted Linux runner<br/>MATLAB R2026a + Compiler SDK]
    B --> C[Portable CTF archive]
    C --> W[Windows runner<br/>JDK + jpackage]
    C --> L[Linux runner<br/>JDK + jpackage]
    C --> M[macOS runner<br/>JDK + jpackage]
    W --> RW[Windows ZIP]
    L --> RL[Linux tar.gz]
    M --> RM[macOS app ZIP]
Loading

MATLAB R2026a introduced the generic MATLAB Compiler SDK API for Java. It produces a platform-independent CTF archive for platform-independent MATLAB code. The remaining jobs only:

  1. compile a small Java launcher;
  2. bundle a Java 17 runtime with jpackage;
  3. add the same CTF archive;
  4. create a native application image and upload it to the release.

What you get

  • one MATLAB compilation instead of three;
  • no MATLAB installation on GitHub-hosted packaging runners;
  • no batch licensing token or MLM_LICENSE_TOKEN secret;
  • Windows x86-64, Linux x86-64, and native Apple silicon packages;
  • a startup splash instead of an apparently frozen application;
  • persistent launcher logs on every platform;
  • native .ico, .png, and .icns application icons;
  • direct GitHub Release uploads without duplicating large release files in Actions artifact storage;
  • one-day artifacts for manual test builds.

Important limitation

The generated application bundles include Java, but do not include MATLAB Runtime. End users must install the free MATLAB Runtime matching the MATLAB release used for compilation. An R2026a CTF requires R2026a Runtime; this is not a >= R2026a dependency.

The launcher detects a missing Runtime, explains which release is required, and opens the official download page.

Prerequisites

On one Linux machine:

  • 64-bit Linux supported by MATLAB R2026a;
  • MATLAB R2026a;
  • MATLAB Compiler;
  • MATLAB Compiler SDK;
  • a normal activated license that can run noninteractively;
  • a GitHub self-hosted runner registered for the repository.

On GitHub-hosted runners, the workflow installs Temurin JDK 17. No MATLAB products are installed there.

Quick start

  1. Click Use this template and create your repository.
  2. Register your activated Linux machine as a repository self-hosted runner.
  3. Confirm MATLAB is installed at /usr/local/MATLAB/R2026a, or edit MATLAB_ROOT in release.yml.
  4. Run Actions → Build cross-platform MATLAB release → Run workflow.
  5. Download the three one-day test artifacts and test them with MATLAB Runtime R2026a.
  6. Publish a GitHub Release. The same workflow uploads the platform archives and SHA256SUMS.txt directly to that release.

See self-hosted runner setup for the complete machine setup.

Adapting the template to your application

The sample builds a small uifigure application. Replace these pieces:

File Change
matlab/launch_demo.m Start your MATLAB UI and return after the first window is visible.
matlab/build_release.m Add application files and folders through AdditionalFiles.
launcher/app.properties Set the display name, CTF filename, entry point, and Runtime release.
.github/workflows/release.yml Set APP_NAME, CTF_NAME, paths, and runner labels.
launcher/icons/app.svg Replace the source icon, then run scripts/generate-icons.sh.

Read customizing the template before replacing the demo with an App Designer application.

Creating a release

Create and publish a release in the GitHub UI, or use the GitHub CLI:

gh release create v1.0.0 --generate-notes --title "v1.0.0"

The release.published event starts the pipeline. A successful release contains:

MatlabCtfDemo-v1.0.0-windows-x86_64.zip
MatlabCtfDemo-v1.0.0-linux-x86_64.tar.gz
MatlabCtfDemo-v1.0.0-macos-arm64.zip
SHA256SUMS.txt

Signing

The template ad-hoc signs the macOS bundle so its internal signature is consistent. It is not notarized. Windows packages are also unsigned. Production distribution should add Apple Developer ID signing/notarization and Windows code signing.

See signing and distribution.

Security

Never run untrusted pull-request code on a self-hosted runner containing a MATLAB license. This workflow intentionally runs only through workflow_dispatch and release.published; it does not run for pull requests.

License

Template code is available under the MIT License. MATLAB, MATLAB Compiler, MATLAB Compiler SDK, and MATLAB Runtime are MathWorks products and are governed by their own licenses. This repository does not distribute MathWorks software.

About

Build MATLAB once on a licensed Linux runner and package native Windows, Linux, and macOS releases without a batch licensing token.

Topics

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages