Generate the SBOM

A Software Bill of Materials (SBOM) lists the components shipped in a product.

MicroEJ SDK exposes the list of Managed Code artifacts embedded in the executable through a dedicated Gradle configuration. It can be used as input by any SBOM generation tool that integrates with Gradle. The sections below show how to generate the SBOM in the SPDX and CycloneDX formats.

Scope of the Generated SBOM

The microejSbomClasspath configuration resolves to the following components:

the application’s runtime dependencies.
the VEE Port components shipped in the executable (Architecture, Packs, runtime implementations).

It does not include:

simulator-only artifacts (Front Panel, Mocks).
test code, build tools, the SDK itself.
native C code linked by the BSP.

The resulting SBOM covers Managed Code only. For a complete product SBOM, combine it with the SBOMs of the other software parts shipped in the product (BSP, third-party native components).

Prerequisites

MicroEJ SDK 6 1.7.0 or later.
An application project, i.e. a project applying the com.microej.gradle.application plugin.
A module repository built with MicroEJ SDK 6 1.8.0 or later, which includes the Maven descriptors of the SDK 5 modules. The Central Repository meets this requirement since the version 4.0.0, released on 2026-09-09. The Developer Repository does not meet this requirement yet.

Warning

An SBOM generation tool reads the Maven descriptor of each module. A module built with MicroEJ SDK 5 carries an Ivy descriptor, not a Maven descriptor. Only a module repository built with MicroEJ SDK 6 1.8.0 or later adds a usable Maven descriptor to such a module. Without this Maven descriptor, the SBOM generation fails, or produces an SBOM which does not list every component shipped in the Executable. This applies to the SPDX format and to the CycloneDX format.

Note

An Application can use an SDK 5 module which the Central Repository does not contain. To get the Maven descriptor of such a module, add the module to your own module repository project, then build the project with MicroEJ SDK 6 1.8.0 or later. Deploy the built module repository on your artifact repository, or declare it in your Gradle configuration.

Modules built with MicroEJ SDK 6 1.2.0 or earlier do not include license information in their POM file. Their entries in the generated SBOM have incomplete license fields. Use module versions published with MicroEJ SDK 6 1.3.0 or later to get complete license information.

Generate an SBOM in SPDX Format

This section uses the Gradle SPDX plugin, which generates SBOMs in the SPDX format.

Configure the Gradle SPDX Plugin

The Gradle SPDX plugin requires JDK 17 or later. The plugin version 0.12.0 writes a document in the SPDX 2.3 format. To get a document in the SPDX 3.0.1 format, refer to Convert a SPDX 2 SBOM to SPDX 3.

Apply the SPDX plugin and declare an SBOM target that reads microejSbomClasspath in the application’s build.gradle.kts:

plugins {
    id("com.microej.gradle.application") version "1.8.0"
    id("org.spdx.sbom") version "0.12.0"
}

spdxSbom {
    targets {
        create("release") {
            configurations.set(listOf("microejSbomClasspath"))

            document {
                name.set("My Product SBOM")
                namespace.set("https://my.company.org/spdx/")
                creator.set("Organization: My Company")
                packageSupplier.set("Organization: My Company")
            }

            // Uncomment the line below to ignore SDK 5 modules
            // ignoreNonMavenDependencies.set(true)
        }
    }
}

Declare the Gradle Plugin Portal as a plugin repository in settings.gradle.kts so that the SPDX plugin can be resolved:

pluginManagement {
    repositories {
        gradlePluginPortal()
    }
}

Refer to the Gradle SPDX plugin documentation for the full list of configuration options, supported Gradle and JDK versions, and advanced use cases.

Generate the SBOM

To generate the SBOM for all declared targets:

./gradlew spdxSbom

To generate the SBOM for a specific target only (for example the release target declared above):

./gradlew spdxSbomForRelease

The SBOM files are written under build/spdx/ in SPDX JSON format.

Warning

The spdxSbom task fails when a module provides no Maven descriptor:

* What went wrong:
Execution failed for task ':spdxSbomForRelease'.
> No POM file found for dependency ej.library.runtime:basictool:1.2.0

The option ignoreNonMavenDependencies.set(true), added to the SPDX target, makes the task succeed. The task then logs Ignoring dependency without POM file: for each module which it skips. The generated SBOM is partial: it omits every SDK 5 module. Use this option only as a temporary workaround, until the module repository meets the requirement given in the Prerequisites section.

Define supplier field

The supplier field defined in the SPDX format identifies the source of the package. It can be defined for the project and for the dependencies:

for the project, define it in the Gradle SPDX plugin configuration in the build.gradle.kts file:

spdxSbom {
    targets {
        create("release") {
            document {
                packageSupplier.set("Organization: My Company")
            }
        }
    }
}

for the dependencies, it must be defined in the dependency project, by setting the organization.name field of the publication:

publishing {
    publications {
        getByName<MavenPublication>("microej") {
            pom {
                organization {
                    name.set("My Company")
                }
            }
        }
    }
}

This configuration sets the organization.name field in the published pom.xml file to the value My Company. Then, this information is extracted when generating the SBOM of a project depending on this module.

Convert a SPDX 2 SBOM to SPDX 3

The Gradle SPDX plugin writes a document in the SPDX 2.3 format. To get a document in the SPDX 3.0.1 format, convert the generated file with the SPDX Java Tools.

Download tools-java-<version>-jar-with-dependencies.jar from the releases page. The tool requires JDK 11 or later.

Run the Convert command on the generated SBOM:

java -jar tools-java-2.0.7-jar-with-dependencies.jar Convert build/spdx/release.spdx.json release.spdx3.json JSON JSONLD

The command writes release.spdx3.json in the SPDX 3.0.1 JSON-LD format.

The SPDX Online Tools convert a single document without a local installation of the SPDX Java Tools.

Include Additional Configurations

If the application ships components that are not part of microejSbomClasspath (for example resources packaged by a custom task), add their configurations to the SBOM target:

configurations.set(listOf("microejSbomClasspath", "myExtraConfiguration"))

Generate an SBOM in CycloneDX Format

This section uses the Gradle CycloneDX plugin, which generates SBOMs in the CycloneDX format.

Configure the Gradle CycloneDX Plugin

Apply the CycloneDX plugin and scope it to the microejSbomClasspath configuration in the application’s build.gradle.kts. The scoping is set on the CyclonedxDirectTask, which also scopes the cyclonedxBom task that aggregates its result:

import org.cyclonedx.gradle.CyclonedxDirectTask

plugins {
    id("com.microej.gradle.application") version "1.8.0"
    id("org.cyclonedx.bom") version "3.2.4"
}

tasks.withType<CyclonedxDirectTask>().configureEach {
    includeConfigs.set(listOf("microejSbomClasspath"))
}

Declare the Gradle Plugin Portal as a plugin repository in settings.gradle.kts so that the CycloneDX plugin can be resolved:

pluginManagement {
    repositories {
        gradlePluginPortal()
    }
}

Refer to the Gradle CycloneDX plugin documentation for the full list of configuration options, supported Gradle and JDK versions, and advanced use cases.

Generate the SBOM

To generate the SBOM:

./gradlew cyclonedxBom

The SBOM files are written under build/reports/cyclonedx/ as bom.json and bom.xml (CycloneDX 1.6 format).

Integrate SBOM Generation into the Build

The steps below apply to any generator. The examples use the SPDX task names from the section above; adapt them to the task of your chosen generator.

Generate the SBOM When Building the Executable

To produce the SBOM every time the executable is built, make the buildExecutable task run the SBOM generation task:

tasks.named("buildExecutable") {
    finalizedBy("spdxSbom")
}

Running ./gradlew buildExecutable then also generates the SBOM.

Publish the SBOM as an Artifact

The MicroEJ SDK declares a Maven publication named microej. Add the generated SBOM to this publication so that it is published together with the Application:

publishing {
    publications.named<MavenPublication>("microej") {
        artifact(tasks.named("spdxSbomForRelease")) {
            classifier = "sbom"
            extension = "spdx.json"
        }
    }
}

Running ./gradlew publish then uploads the SBOM alongside the Application, as <module>-<version>-sbom.spdx.json.