Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/lefou/mill-osgi

OSGi Support for Mill build tool
https://github.com/lefou/mill-osgi

bnd build-tool mill mill-plugin osgi osgi-bundle plugin scala

Last synced: 4 months ago
JSON representation

OSGi Support for Mill build tool

Awesome Lists containing this project

README 

        
= 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



.File: `build.sc` (mill {mill-platform})

[source,scala,subs="verbatim,attributes"]

----

// 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.



----

$ 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 {mill-platform})

[source,scala,subs="verbatim,attributes"]

----

// 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.



me::

+

--

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].



If you like my work, please star it on GitHub. You can also support me via https://github.com/sponsors/lefou[GitHub Sponsors].

--



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



* 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

:prev-version: 0.1.2

:version: 0.2.0



* Update mill API to 0.6.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



* Use the `artifactId` as base for the default `Bundle-SymbolicName`

* Added `exportContents` target



_See 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



* 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 {projectHome}/compare/{prev-version}...{version}[commits since {prev-version}]._



=== 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