Kotlin Packaging & Publishing

This page will discuss common topics around packaging and publishing your Kotlin projects for others to use

Building Executable Assemblies

Mill’s built in .assembly task makes it easy to generate an executable assembly jar from any JVM module. You can also customize the assembly jar as shown below:

build.mill (download, browse)
package build
import mill._, kotlinlib._
import mill.javalib.Assembly._

object foo extends KotlinModule {

  def kotlinVersion = "1.9.24"

  def mainClass = Some("foo.FooKt")

  def moduleDeps = Seq(bar)
  def assemblyRules = Seq(
    // all application.conf files will be concatenated into single file
    Rule.Append("application.conf"),
    // all *.conf files will be concatenated into single file
    Rule.AppendPattern(".*\\.conf"),
    // all *.temp files will be excluded from a final jar
    Rule.ExcludePattern(".*\\.temp"),
    // the `shapeless` package will be relocated under the `shade` package
    Rule.Relocate("shapeless.**", "shade.shapless.@1")
  )
}

object bar extends KotlinModule {
  def kotlinVersion = "1.9.24"
}

The most common way of configuring an assembly is excluding some files from a final jar (like signature files, and manifest files from library jars), and merging duplicated files (for instance reference.conf files from library dependencies). This is done by overriding def assemblyRules as shown above

By default mill excludes all *.sf, *.dsa, *.rsa, and META-INF/MANIFEST.MF files from assembly, and concatenates all reference.conf files. You can also define your own merge/exclude rules.

> ./mill foo.assembly

> unzip -p ./out/foo/assembly.dest/out.jar application.conf || true
Bar Application Conf
Foo Application Conf

> java -jar ./out/foo/assembly.dest/out.jar
Loaded application.conf from resources:...
...Foo Application Conf
...Bar Application Conf

Note that when running the assembly directly via ./out.jar, you can configure JVM flags via the JAVA_OPTS environment variable, and select the JVM to use via JAVA_HOME.

> JAVA_OPTS=-Dtest.property=1337 ./out/foo/assembly.dest/out.jar
Loaded test.property: 1337

Building Native Image Binaries with Graal VM

build.mill (download, browse)
package build
import mill._, kotlinlib._
import mill.define.ModuleRef

object foo extends KotlinModule with NativeImageModule {

  def kotlinVersion = "1.9.24"

  def zincWorker = ModuleRef(ZincWorkerGraalvm)
}

object ZincWorkerGraalvm extends ZincWorkerModule {
  def jvmId = "graalvm-community:17.0.7"
}

This example uses NativeImageModule to generate a native executable using Graal VM. We recommend you configure a specific JDK version via a custom ZincWorkerModule overriding def jvmId (shown above), as not every JVM can build Graal native images.

> ./mill show foo.nativeImage
GraalVM Native Image: Generating...native-executable...
Finished generating...native-executable...

> ./out/foo/nativeImage.dest/native-executable
Hello, World!

For another example building a slightly less trivial project into a Graal native image, see below:

build.mill (download, browse)
package build
import mill._, kotlinlib._
import mill.define.ModuleRef

object foo extends KotlinModule with NativeImageModule {
  def kotlinVersion = "1.9.24"

  def mainClass = Some("foo.FooKt")

  def nativeImageOptions = Seq(
    "--no-fallback",
    "-Os",
    "--initialize-at-build-time=com.github.ajalt.mordant.internal.nativeimage.NativeImagePosixMppImpls"
  )

  def ivyDeps = Agg(
    ivy"com.github.ajalt.clikt:clikt-jvm:4.4.0",
    ivy"org.jetbrains.kotlinx:kotlinx-html-jvm:0.11.0"
  )

  def zincWorker = ModuleRef(ZincWorkerGraalvm)
}

object ZincWorkerGraalvm extends ZincWorkerModule {
  def jvmId = "graalvm-community:23.0.2"
}

This example shows how to generate native images for projects using third-party libraries, in this case Clikt and KotlinX-HTML. We also demonstrate setting nativeImageOptions, in this case using -Os to optimize for the smallest binary size, which is available in the graalvm-community:23 JDK selected above. The --initialize-at-build-time flag is also necessary for this particular set of libraries and flags.

> ./mill show foo.nativeImage

> ./out/foo/nativeImage.dest/native-executable --text hello-world
<h1>hello-world</h1>

You can see the Graal documentation to see what flags are available:

Or access the native-image compiler directly via show foo.nativeImageTool if you want to experiment it or view its --help text to see what you need to pass to nativeImageOptions:

> ./mill show foo.nativeImageTool # mac/linux
".../bin/native-image"

> ./mill show foo.nativeImageTool # windows
".../bin/native-image.cmd"

For more details on using Graal, check the this blog post:

Publishing Locally

build.mill (download, browse)
package build
import mill._, kotlinlib._, publish._

object foo extends KotlinModule with PublishModule {

  def mainClass = Some("foo.FooKt")

  def kotlinVersion = "1.9.24"

  def publishVersion = "0.0.1"

  def pomSettings = PomSettings(
    description = "Hello",
    organization = "com.lihaoyi",
    url = "https://github.com/lihaoyi/example",
    licenses = Seq(License.MIT),
    versionControl = VersionControl.github("lihaoyi", "example"),
    developers = Seq(Developer("lihaoyi", "Li Haoyi", "https://github.com/lihaoyi"))
  )
}

This is an example KotlinModule with added publishing capabilities via PublishModule. This requires that you define an additional publishVersion and pomSettings with the relevant metadata, and provides the .publishLocal and publishSigned tasks for publishing locally to the machine or to the central maven repository

> mill foo.publishLocal
Publishing Artifact(com.lihaoyi,foo,0.0.1) to ivy repo...

publishLocal publishes the artifacts to the ~/.ivy2/local folder on your machine, allowing them to be resolved by other projects and build tools. This is useful as a lightweight way of testing out the published artifacts, without the setup overhead and long latencies of publishing artifacts globally accessible to anyone in the world.

Publishing to Sonatype Maven Central

Once you’ve mixed in PublishModule, apart from publishing locally, you can also publish your project’s modules to maven central

GPG

If you’ve never created a keypair before that can be used to sign your artifacts you’ll need to do this. Sonatype’s GPG Documentation has the instructions on how to do this

Publishing Secrets

Mill uses the following environment variables as a way to pass the necessary secrets for publishing:

# The LHS and RHS of the User Token, accessible through the sonatype
# website `Profile` / `User Token` / `Access User Token`
export MILL_SONATYPE_USERNAME=...
export MILL_SONATYPE_PASSWORD=...

# The base-64 encoded PGP key, which can be encoded in the following way
# for each OS:
#
# MacOS or FreeBSD
# gpg --export-secret-key -a $LONG_ID | base64
#
# Ubuntu (assuming GNU base64)
# gpg --export-secret-key -a $LONG_ID | base64 -w0
#
# Arch
# gpg --export-secret-key -a $LONG_ID | base64 | sed -z 's;\n;;g'
#
# Windows
# gpg --export-secret-key -a %LONG_ID% | openssl base64
export MILL_PGP_SECRET_BASE64=...

# The passphrase associated with your PGP key
export MILL_PGP_PASSPHRASE=...

Publishing

You can publish all eligible modules in your Mill project using the default task of the External Module mill.scalalib.PublishModule:

mill mill.scalalib.PublishModule/

You can also specify individual modules you want to publish via a selector:

mill mill.scalalib.PublishModule/ --publishArtifacts foo.publishArtifacts

The default URL for publishing to sonatype’s Maven Central is oss.sonatype.org. Newer projects registered on sonatype may need to publish using s01.oss.sonatype.org. In that case, you can pass in a --sonatypeUri:

mill mill.scalalib.PublishModule/ \
        --sonatypeUri https://s01.oss.sonatype.org/service/local

This also allows you to publish to your own internal corporate sonatype deployment, by passing in --sonatypeUri example.company.com instead.

Since Feb. 2021 any new Sonatype accounts have been created on s01.oss.sonatype.org, so you’ll want to ensure you set the relevant URIs to match.

The symptom of using the "wrong" URL for publishing is typically a 403 error code, in response to the publish request.

See https://central.sonatype.org/publish/publish-guide/#releasing-to-central

Typically

Publishing Using Github Actions

To publish on Github Actions, you can use something like this:

# .github/workflows/publish-artifacts.yml
name: Publish Artifacts
on:
  push:
    tags:
      - '**'
  workflow_dispatch:
jobs:
  publish-artifacts:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-java@v3
        with:
          distribution: 'temurin'
          java-version: '17'
      - run: ./mill mill.scalalib.PublishModule/
        env:
          MILL_PGP_PASSPHRASE: ${{ secrets.MILL_PGP_PASSPHRASE }}
          MILL_PGP_SECRET_BASE64: ${{ secrets.MILL_PGP_SECRET_BASE64 }}
          MILL_SONATYPE_PASSWORD: ${{ secrets.MILL_SONATYPE_PASSWORD }}
          MILL_SONATYPE_USERNAME: ${{ secrets.MILL_SONATYPE_USERNAME }}

Where MILL_PGP_PASSPHRASE, MILL_PGP_SECRET_BASE64, MILL_SONATYPE_PASSWORD, and MILL_SONATYPE_USERNAME configured for the repository’s or organization’s Github Actions workflows. See Using Secrets in Github Actions for more details.

Non-Staging Releases (classic Maven uploads)

If the site does not support staging releases as oss.sonatype.org and s01.oss.sonatype.org do (for example, a self-hosted OSS nexus site), you can pass in the --stagingRelease false option to simply upload release artifacts to corresponding maven path under sonatypeUri instead of staging path.

mill mill.scalalib.PublishModule/ \
        --publishArtifacts foo.publishArtifacts \
        --sonatypeCreds lihaoyi:$SONATYPE_PASSWORD \
        --sonatypeUri http://example.company.com/release \
        --stagingRelease false

Publishing to other repositories

While Sonatype Maven Central is the default publish repository for JVM ecosystem projects, there are also others that you can use. Mill supports these largely through contrib plugins:

jlink and jpackage

Mill has builtin support for the JLink and JPackage command line tools. For more details, see: