mill-osgi - Build OSGi Bundles with mill

Plug-in to build OSGi bundles with the mill build tool

Table of Contents

• Quickstart
• Example using the BuildMode.CalculateManifest
• Configuration
• Defaults
  • Build Mode
  • Export-Package and Private-Package
  • Bundle-SymbolicName
• Version Compatibility Matrix
• Download
• License
• About
• Changelog
  • mill-osgi 0.5.0 - 2023-06-24
  • mill-osgi 0.4.0 - 2022-01-16
  • mill-osgi 0.3.2 - 2020-12-02
  • mill-osgi 0.3.1 - 2020-11-16
  • mill-osgi 0.3.0 - 2020-05-15
  • mill-osgi 0.2.0 - 2020-02-24
  • mill-osgi 0.1.2 - 2020-01-19
  • mill-osgi 0.1.1 - 2020-01-08
  • mill-osgi 0.1.0 - 2019-09-13
  • mill-osgi 0.0.6 - 2019-02-15
  • mill-osgi 0.0.5 - 2018-12-14
  • mill-osgi 0.0.4 - 2018-11-20
  • mill-osgi 0.0.3 - 2018-11-02
  • mill-osgi 0.0.2 - 2018-10-18
  • mill-osgi 0.0.1 - 2018-10-10

Quickstart

File: build.sc (mill 0.11)

// build.sc default imports
import mill._, mill.scalalib._
// This import the mill-osgi plugin
import $ivy.`de.tototec::de.tobiasroeser.mill.osgi_mill0.11:0.5.0`
import de.tobiasroeser.mill.osgi._

object project extends ScalaModule with OsgiBundleModule {

  def bundleSymbolicName = "com.example.project"

  def osgiHeaders = T{ super.osgiHeaders().copy(
    `Export-Package`   = Seq("com.example.api"),
    `Bundle-Activator` = Some("com.example.internal.Activator")
  )}

  // other settings ...

}

Use mill 0.6.0 or newer, to build the OSGi bundle.

$ mill project.osgiBundle
[27/38] project.compile
[info] Compiling 1 Scala source to /tmp/project/out/project/compile/dest/classes ...
[info] Done compiling.
[38/38] project.osgiBundle

Please note, that the default jar target is also overriden, so that it depends on osgiBundle and in fact it returns the exact same bundle.

$ mill show project.jar
[1/1] show
[39/39] project.jar
"ref:14551bd1:/tmp/project/out/project/osgiBundle/dest/out.jar"

Example using the BuildMode.CalculateManifest

File: build.sc (mill 0.11)

// build.sc default imports
import mill._, mill.scalalib._
// This import the mill-osgi plugin
import $ivy.`de.tototec::de.tobiasroeser.mill.osgi::0.5.0`
import de.tobiasroeser.mill.osgi._

object project extends ScalaModule with OsgiBundleModule {

  override def osgiBuildMode = OsgiBundleModule.BuildMode.CalculateManifest

  override def scalaVersion = "2.13.11"

  def bundleSymbolicName = "com.example.project"

  def osgiHeaders = T{ super.osgiHeaders().copy(
    `Export-Package`   = Seq("com.example.api"),
    `Bundle-Activator` = Some("com.example.internal.Activator")
  )}

  // other settings ...

}

Configuration

To produce OSGi bundles, your module has to implement de.tobiasroeser.mill.osgi.OsgiBundleModule.

Configuration options

• def osgiBuildMode: BuildMode - The build mode. Defaults to BuildMode.ReplaceJarTarget, in which the jar target delegates to osgiBundle. You can also select BuildMode.CalculateManifest, in which only the manifest entries will be generated with bnd tool, but the JAR is creates by the regular (derived) jar target.

• def bundleVersion: T[String] - The bundle version. If the module is a PublishModule, it defaults to PublishModule.publishVersion.

• def bundleSymbolicName: T[String] - The bundle symbolic name. If the module is a PublishModule, it derives a default from from PublishModule.artifactMetadata.

• def reproducibleBundle: T[Boolean] - Create a reproducible bundle file. To achieve that, some properties of the resulting JAR will be adjusted, e.g. sorted manifest and JAR entries, unified file create time, etc. Defaults to true.

• def embeddedJars: T[Seq[PathRef]] - Embed these JAR files and also add them to the bundle classpath.

• def explodedJars: T[Seq[PathRef]] - Embed the content of the given JAR files into the bundle.

• def exportContents: T[Seq[String]] - Exports the given packages but does not try to include them from the class path. The packages should be loaded with alternative means.

• def osgiHeaders: T[OsgiHeaders] - Various OSGi headers defining the OSGi bundle. You should always use OsgiHeaders.copy to customize some headers to not loose useful defaults.

• def includeSources: T[Boolean] - Iff true include sources in the final bundle under OSGI-OPT/src. Defaults to false.

• def includeResource: T[Seq[String]] - Resources to include into the final bundle. Defaults to include resources defined with JavaModule.resources.

• def additionalHeaders: T[Map[String, String]] - Additional headers to add to the bundle manifest. All headers added here will be applied after osgiHeaders and thus override previously defined values. Be careful to not add standard OSGi headers here, but via osgiHeaders.

• def osgiBundle: T[PathRef] - Build the OSGi Bundle.

• def manifest: T[Jvm.JarManifest] - Creates a manifest representation which can be modified or replaced. The default implementation generates OSGi manifest entries from compiled classes with bnd tool and additionally adds a Main-Class, if defined in .

Defaults

By default mill-osgi tries to provide some sensible default values based on the current build setup.

Build Mode

You can choose between two build modes:

BuildMode.ReplaceJarTarget

This is the default build mode. This was the first implemented build mode and was also the way some OSGi plugins in other build tools worked (e.g. bundle-maven-plugin, sbt-osgi). In this mode, the JAR file and it’s manifest is produced by the bnd tool based on the compiled classfiles, the dependencies and the plugin instructions. This happens in the build target osgiBundle which is linked from the override jar target.

BuildMode.CalculateManifest

This is a new mode and somewhat experimental. In this mode, only the manifest entries are calculated with the bnd tool (by processing the plugin instructions, compiled classfiles and the classpath) in the manifest target. The actual jar file creation is derived from super.jar target, which comes from JavaModule. This mode might become the default eventually, as the process is better suited to the way how mill works.

Export-Package and Private-Package

By default, all output packages of the compile task will be added to the Private-Package header. No packages will be exported via Export-Package.

Bundle-SymbolicName

If the module does not extends PublishModule, the bundle symbolic name will be initializes with JavaModule.artifactId.

If the module extends PublishModule, the Bundle-SymbolicName is computed using from PublishModule.pomSettings.organization and JavaModule.artifactId. If the organization or the last segment of the organization is a prefix of the artifactName, than that redundant part is omitted.

Version Compatibility Matrix

Mill is still in active development, and has no stable API yet. Hence, not all mill-osgi versions work with every mill version.

The following table shows a matrix of compatible mill and mill-osgi versions.

Table 1. Version Compatibility Matrix

mill-osgi	mill
0.5.0	0.6.0 - 0.11.x
0.4.0	0.6.0 - 0.10.x
0.3.2	0.6.0 - 0.9.3
0.3.1	0.6.0 - 0.8.0
0.3.0	0.6.0 - 0.8.0
0.2.0	0.6.0 - 0.6.3
0.1.2	0.5.7 - 0.5.9
0.1.1	0.5.7 - 0.5.9
0.1.0	0.3.6 - 0.5.3
0.0.6	0.3.6 - 0.5.3
0.0.5	0.3.5
0.0.4	0.3.2
0.0.3	0.3.2
0.0.2	0.2.8
0.0.1	0.2.8

Download

You can download binary releases from Maven Central.

Please make sure to use the correct mill platform suffix matching your used mill version.

License

This project is published under the Apache License, Version 2.0.

About

mill

Mill is a Scala-based open source build tool. In my opinion the best build tool for the JVM. It is fast, reliable and easy to understand.

me

I’m a professional software developer and love to do open source. I’m actively developing and maintaining mill as well as several mill plugins.

If you like my work, please star it on GitHub. You can also support me via GitHub Sponsors.

Contributing

If you found a bug or have a feature request, please open a new issue. I also accept pull requests.

Changelog

mill-osgi 0.5.0 - 2023-06-24

• Added support for Mill 0.11 API

• Various dependency updates

mill-osgi 0.4.0 - 2022-01-16

• Improved BuildMode.CalculateManifest mode

• Added coverage data collected from integration tests

• Support for Mill 0.10

• Updated bndlib version to 6.1.0

• Some internal improvements and fixes

mill-osgi 0.3.2 - 2020-12-02

• Support for mill API 0.9.3

• Introduced new artifact name suffix for the mill API (_mill0.9) to enable continuous backwards compatibility

mill-osgi 0.3.1 - 2020-11-16

• Version bump bndlib to 5.2.0

• Version bump scalatest to 3.2.2

• Various build related improvements

  • Github Actions instead of Travis-CI

  • Use of mill-vcs-version plugin

mill-osgi 0.3.0 - 2020-05-15

• Added new build mode CalculateManifest, which only generates the manifest properties but leaves the jar creation to JavaModule.

• Cross published for mill 0.6 (Scala 2.12) and 0.7 (Scala 2.13)

mill-osgi 0.2.0 - 2020-02-24

• Update mill API to 0.6.0

See list of commits since 0.1.2.

mill-osgi 0.1.2 - 2020-01-19

• Use the artifactId as base for the default Bundle-SymbolicName

• Added exportContents target

See list of commits since 0.1.1.

mill-osgi 0.1.1 - 2020-01-08

• Version bump mill API to 0.5.7

• Version bump to bndlib-4.3.1

• Version bump to scala 2.12.10

See list of commits since 0.1.0.

mill-osgi 0.1.0 - 2019-09-13

• Version bump to bndlib-4.2.0

• Fixed handling of empty compile result

• osgiBundle now produces a proper named jar (symbolic name and version)

• Some internal improvements

• Improved documentation

mill-osgi 0.0.6 - 2019-02-15

• Version bump to mill-0.3.6 and use of new mill-api

• Improved integration test setup

• Added runtime detection of possibly incompatible mill runtime version

mill-osgi 0.0.5 - 2018-12-14

• Reworked integration test setup

• Version bump to mill-0.3.5 and use of os-lib

mill-osgi 0.0.4 - 2018-11-20

• Added explicit scala-library dependency to released pom.xml

mill-osgi 0.0.3 - 2018-11-02

• Changed packaging / pom dependency information so that loading into mill excludes mill dependencies

mill-osgi 0.0.2 - 2018-10-18

• Improved default bundle symbolic name algorithm

• Added support for -includeresource

• Improved source docs

• Don’t add non-existing resources to avoid bnd warnings/errors

• Add more default headers when project is a PublishModule

mill-osgi 0.0.1 - 2018-10-10

• Initial early release to gain user feedback