Multi-architecture native library distribution and JVM application packaging for Scala.

Three SBT AutoPlugins and a core library:

What do they do? Let's take a look at some examples.

In project/plugins.sbt:

addSbtPlugin("com.kubuszok" % "sbt-multiarch-scala" % "<version>")

// Required dependencies
addSbtPlugin("org.scala-native" % "sbt-scala-native" % "0.5.10")

In build.sbt:

lazy val myApp = (project in file("my-app"))
  .enablePlugins(NativeProviderPlugin)
  .settings(
    scalaVersion := "3.8.3",
    libraryDependencies ++= Seq(
      // STTP on Scala Native requires libcurl, normally you would
      // have to have it installed on your system, or SN would not
      // be able to link the complete binary...
      "com.softwaremill.sttp.client4" %%% "core" % "4.0.19",
      // ...but here we just need to add a dependency and NativeProviderPlugin
      // will extract the necessary native artifact and set up SN flags!
      "com.kubuszok" % "sn-provider-curl" % "<version>"
    )
  )

sbt nativeLink

That's it. The plugin automatically discovers sn-provider.json manifests on the classpath, extracts native libraries for your platform, and configures Scala Native's nativeConfig with the correct linker flags.

lazy val myApp = (project in file("my-app"))
  .enablePlugins(MultiArchJvmReleasePlugin)
  .settings(
    Compile / mainClass := Some("com.example.Main"),
    releaseTargets := Map(
      Platform.LinuxX86_64    -> "https://cdn.azul.com/zulu/bin/zulu25-...-linux_x64.tar.gz",
      Platform.MacosAarch64   -> "https://cdn.azul.com/zulu/bin/zulu25-...-macosx_aarch64.tar.gz",
      Platform.WindowsX86_64  -> "https://cdn.azul.com/zulu/bin/zulu25-...-win_x64.zip",
      // ... all 6 desktop platforms
    )
  )

sbt "releasePlatform linux-x86_64"   # single platform
sbt releaseAll                       # all configured platforms
sbt releasePackage                   # simple mode (system JDK required)

If you used JDKPackager you might wonder what's the fuss?

Well, JDKPackagerPlugin can only build package for the currently used JDK on the current platform. If you need to package for several architectures, you'd have to e.g. use GitHub actions with multiple different runners (one for each platform) to do it for you.

MultiArchJvmReleasePlugin lets you build on your own computer packages for multiple different architectures, and let you select the JDK to use for each of them. That means that you can build all the release artifacts completely offline, on your own computer!

For JVM projects that need to load native shared libraries at runtime:

// Add dependency
libraryDependencies += "com.kubuszok" %% "multiarch-core" % "<version>"

import multiarch.core.{ NativeLibLoader, ProviderType }

// Auto-discover and load all libraries from jni-provider.json on classpath
NativeLibLoader.loadAll(ProviderType.Jni)

// Or load specific configs
NativeLibLoader.loadConfigs(ProviderType.Panama, Set("mylib"))

// Or load a single library by name
val path = NativeLibLoader.load("mylib")

Build your native library for each target platform. For Scala Native, you need static archives (.a / .lib). For JNI/Panama, you need shared libraries (.so / .dylib / .dll).

Choose the right manifest filename for your provider type:

(There is no difference between jni-provider.json and pnm-provider.json, but different naming helps prevent accidentally using a wrong artifact if there are multiple versions).

Create the manifest in src/main/resources/.

For static libraries linked at compile time. The flags-groups field is required — it tells the Scala Native linker which system libraries and frameworks to link:

{
  "provider-schema-version": "0.1.0",
  "provider-name": "mylib",
  "configs": [
    {
      "config-name": "mylib",
      "linux-x86_64": {
        "binary": "libmylib.a",
        "flags-groups": [["-lpthread"], ["-ldl"]]
      },
      "linux-aarch64": {
        "binary": "libmylib.a",
        "flags-groups": [["-lpthread"], ["-ldl"]]
      },
      "macos-x86_64": {
        "binary": "libmylib.a",
        "flags-groups": [["-framework", "Security"]]
      },
      "macos-aarch64": {
        "binary": "libmylib.a",
        "flags-groups": [["-framework", "Security"]]
      },
      "windows-x86_64": {
        "binary": "mylib.lib",
        "flags-groups": [["-lws2_32"], ["-ladvapi32"]]
      },
      "windows-aarch64": {
        "binary": "mylib.lib",
        "flags-groups": [["-lws2_32"], ["-ladvapi32"]]
      }
    }
  ]
}

For shared libraries loaded at runtime. No flags-groups — dynamic loading has no linker flags:

{
  "provider-schema-version": "0.1.0",
  "provider-name": "mylib",
  "configs": [
    {
      "config-name": "mylib",
      "linux-x86_64":    { "binary": "libmylib.so" },
      "linux-aarch64":   { "binary": "libmylib.so" },
      "macos-x86_64":    { "binary": "libmylib.dylib" },
      "macos-aarch64":   { "binary": "libmylib.dylib" },
      "windows-x86_64":  { "binary": "mylib.dll" },
      "windows-aarch64": { "binary": "mylib.dll" },
      "android-aarch64": { "binary": "libmylib.so" },
      "android-armv7":   { "binary": "libmylib.so" },
      "android-x86_64":  { "binary": "libmylib.so" }
    }
  ]
}

Bundle your native files following the platform-classifier directory convention:

my-provider.jar
├── sn-provider.json          (or jni-provider.json / pnm-provider.json)
└── native/
    ├── linux-x86_64/
    │   └── libmylib.a        (or .so / .dylib / .dll)
    ├── linux-aarch64/
    │   └── libmylib.a
    ├── macos-x86_64/
    │   └── libmylib.a
    ├── macos-aarch64/
    │   └── libmylib.a
    ├── windows-x86_64/
    │   └── mylib.lib
    └── windows-aarch64/
        └── mylib.lib

In your build.sbt:

lazy val myProvider = project
  .settings(
    name := "my-provider",
    autoScalaLibrary := false,
    crossPaths := false,
    Compile / packageBin / mappings ++= {
      val nativesDir = baseDirectory.value / "natives"
      Platform.desktop.flatMap { p =>
        val platDir = nativesDir / p.classifier
        if (platDir.exists())
          IO.listFiles(platDir).filter(_.isFile).map(f => f -> s"native/${p.classifier}/${f.getName}").toSeq
        else Seq.empty
      }
    }
  )

Publish your provider JAR. Consumers simply add it as a dependency — the plugin handles discovery, extraction, and linker configuration automatically.

I suggest the following naming convention:

• sn-provider-library-name — artifacts providing native libraries statically linked with Scala Native
• jni-provider-library-name — artifacts providing native libraries dynamically loaded via JNI
• pnm-provider-library-name — artifacts providing native libraries dynamically loaded via Panama API

It isn't required by the infrastructure to work, but when sorting dependencies by the name, all the native libraries will be grouped together naturally.

A JAR should contain at most one of these files.

No flags-groups or stub — dynamically loaded libraries have no linker flags.

• Present (e.g. "binary": "libcurl.a"): The named file is extracted from the JAR and its full path is passed to the linker (SN) or loaded at runtime (JNI/Panama), along with flags-groups if applicable.
• Absent (SN only): No library is extracted or linked. Only flags-groups from this config contribute to the linker command. Use this for configs that only provide system library flags.

Flag groups from all providers are collected and deduplicated by exact group equality. This means ["-framework", "Security"] from two different providers appears only once in the final linker command. Individual flags within a group are kept together.

Cross-compile Scala Native to non-host platforms using zig:

lazy val myAppLinux = (project in file("my-app-linux"))
  .enablePlugins(NativeProviderPlugin, MultiArchNativeReleasePlugin)
  .settings(
    zigCrossTarget := Some(Platform.LinuxX86_64)
  )

Requires zig installed on PATH.

Apache 2.0