OSGi Support for Mill build tool
APACHE-2.0 License
= mill-osgi - Build OSGi Bundles with mill :mill-min-version: 0.6.0 :mill-osgi-version: 0.5.0 :mill-platform: 0.11 :example-scala-version: 2.13.11 :projectHome: https://github.com/lefou/mill-osgi :toc: :toc-placement: preamble
ifdef::env-github[] image:https://github.com/lefou/mill-osgi/workflows/.github/workflows/build.yml/badge.svg["GitHub Actions Build Status", link="https://github.com/lefou/mill-osgi/actions"] image:https://codecov.io/gh/lefou/mill-osgi/branch/main/graph/badge.svg["Test Coverage (Codecov.io)", link="https://codecov.io/gh/lefou/mill-osgi"] endif::[]
Plug-in to build OSGi bundles with the https://github.com/lihaoyi/mill[mill build tool]
== Quickstart
build.sc
(mill {mill-platform})// build.sc default imports
import mill., mill.scalalib.
// This import the mill-osgi plugin
import $ivy.de.tototec::de.tobiasroeser.mill.osgi_mill{mill-platform}:{mill-osgi-version}
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 {mill-min-version} or newer, to build the OSGi bundle.
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.
== Example using the BuildMode.CalculateManifest
build.sc
(mill {mill-platform})// build.sc default imports
import mill., mill.scalalib.
// This import the mill-osgi plugin
import $ivy.de.tototec::de.tobiasroeser.mill.osgi::{mill-osgi-version}
import de.tobiasroeser.mill.osgi._
object project extends ScalaModule with OsgiBundleModule {
override def osgiBuildMode = OsgiBundleModule.BuildMode.CalculateManifest
override def scalaVersion = "{example-scala-version}"
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 link:core/src/de/tobiasroeser/mill/osgi/OsgiBundleModule.scala[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 [[mainClass]].
== 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.
.Version Compatibility Matrix [options="header"] |=== | 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 https://search.maven.org/search?q=g:de.tototec[Maven Central].
Please make sure to use the correct mill platform suffix matching your used mill version.
== License
This project is published under the https://www.apache.org/licenses/LICENSE-2.0[Apache License, Version 2.0].
== About
mill:: https://github.com/lihaoyi/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.
https://github.com/lefou/[I'm] a professional software developer and love to do open source. I'm actively developing and maintaining mill as well as https://github.com/lefou?utf8=%E2%9C%93&tab=repositories&q=topic%3Amill&type=&language=[several mill plugins].
Contributing:: If you found a bug or have a feature request, please open a {projectHome}/issues[new issue]. I also accept {projectHome}/pulls[pull requests].
== Changelog
=== mill-osgi 0.5.0 - 2023-06-24
=== mill-osgi 0.4.0 - 2022-01-16
BuildMode.CalculateManifest
mode=== mill-osgi 0.3.2 - 2020-12-02
_mill0.9
) to enable continuous backwards compatibility=== mill-osgi 0.3.1 - 2020-11-16
=== mill-osgi 0.3.0 - 2020-05-15
CalculateManifest
, which only generates the manifest properties but leaves the jar creation to JavaModule
.=== mill-osgi 0.2.0 - 2020-02-24 :prev-version: 0.1.2 :version: 0.2.0
See list of {projectHome}/compare/{prev-version}...{version}[commits since {prev-version}].
=== mill-osgi 0.1.2 - 2020-01-19 :prev-version: 0.1.1 :version: 0.1.2
artifactId
as base for the default Bundle-SymbolicName
exportContents
targetSee list of {projectHome}/compare/{prev-version}...{version}[commits since {prev-version}].
=== mill-osgi 0.1.1 - 2020-01-08 :prev-version: 0.1.0 :version: 0.1.1
See list of {projectHome}/compare/{prev-version}...{version}[commits since {prev-version}].
=== 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
PublishModule
=== mill-osgi 0.0.1 - 2018-10-10