Creating and Using a Developer Package

A Manufacturer who builds a Multi-Sandbox device based on MicroEJ VEE may want to open their platform to third-party developers — partners, customers, or an independent software vendor ecosystem. However, sharing the full internal toolchain is not desirable: it would expose proprietary Kernel source code and internal build infrastructure.

A Developer Package solves this by giving third-party developers everything they need to write, build, and test Sandboxed Applications, for the Manufacturer’s device, without disclosing any protected intellectual property. The Manufacturer retains full control over what gets deployed. This is useful, for example, when building an IoT platform where independent software vendors develop value-added applications, or when a device maker wants to let enterprise customers extend the firmware with custom logic while keeping the platform secure and stable.

For more information on the Kernel and Sandboxed Applications design, refer to this section.

This tutorial explains, as the Manufacturer, how to build and deliver the Application Developer Package components. It assumes the Manufacturer already has a working Multi-Sandbox Kernel Application project and a Multi-Sandbox VEE Port.

The Developer Package delivery consists of the following items:

  • Module Repository: the modules required to develop Applications.

  • Kernel Stripped Executable: which can be flashed in the device and allows to build the Applications binary files.

  • Virtual Device: which allows to execute the Applications in the Simulator and build the Applications binary files.

  • Javadoc: the Javadoc of the APIs available for the Applications development.

  • Documentation: which explains how to use the Developer Package to develop Applications.

  • (Optional) A sample Application project demonstrating how to use the Kernel API.

The following directory structure is the recommended layout for delivering the Developer Package:

└── my-product-name
    ├── bin
    │   ├── executable/
    │   │   └── <target>/     # One per Kernel target
    │   └── virtualDevice/
    │       └── <target>/     # One per Kernel target
    ├── doc             # Documentation
    ├── javadoc         # Javadoc
    ├── repository      # Module Repository
    ├── src             # Sources
    ├── CHANGELOG.md
    └── README.md

The bin/ directory contains the Kernel binary artifacts: the Stripped Executable and the Virtual Device, organized by target so that multiple hardware variants can coexist in the same delivery. The repository/ directory contains the Module Repository. The src/ directory can include sample Application projects. The doc/ and javadoc/ directories contain the Manufacturer’s documentation and the Kernel API Javadoc.

The steps below explain how to build each component of this structure.

Step 1 — Create the Developer Package Project

Clone the Developer Package Project Template GitHub repository:

$ git clone https://github.com/MicroEJ/Tool-Project-Template-Developer-Package.git

This creates the recommended directory structure described above.

Step 2 — Configure the Application Developer Mode

A bunch of initial configuration must be done after the git repository clone. It is dispatched in several files:

  • gradle.properties

    • systemProp.package.module.name: defines the name of the generated archive.

    • systemProp.package.group.name: defines the group of the source projects.

    • systemProp.package.version: defines the version of the source projects.

    • systemProp.app.developer.mode.enabled: defines if the generated package is targeted for Application developer. It must be set to true.

  • settings.gradle.kts

    • rootProject.name: defines the name of the source projects.

Step 3 — Configure the Module Repository

The Module Repository bundles the Kernel API and the libraries required to develop Sandboxed Applications into a portable ZIP file that Application developers can use locally. It can be configured as a full repository — containing every required dependency so that no external repository is needed — or as a partial repository that complements another repository, such as the MicroEJ Central Repository, for dependencies not included in the bundle.

Declare the modules to include in the repository/build.gradle.kts file of the cloned project:

group = "com.mycompany"
version = "1.0.0"

dependencies {
    // Kernel API (classes exposed to application developers)
    microejModule("com.mycompany:my-kernel-api:1.0.0")

    // Libraries required by applications
    microejModule("ej.api:edc:1.3.3")
    microejModule("ej.api:bon:1.4.0")
    microejModule("ej.library.ui:mwt:3.7.1")
}

Note

Transitive dependencies of the declared modules are included in the repository by default.

Partial Repository

If application developers also need to resolve modules from other repositories, such as the MicroEJ Central Repository, configure the Module Repository as a Partial Repository. To do so, create the file named module-repository.gradle.kts as described in the Configure a Partial Repository section. This file is packaged inside the Module Repository ZIP and applied by Application developers to configure their projects.

Once the project is configured, you can check the result by executing the following command in the Module Repository subproject:

$ ./gradlew buildModuleRepository

The Module Repository ZIP is generated in the build/libs/ folder of the project.

Refer to Build the Repository for additional build options.

Embed MicroEJ SDK

If you prefer embedding the MicroEJ SDK in the Module Repository (for example to provide a Full Repository), declare the following dependencies:

microejModule("com.microej.gradle:plugins:1.7.0")
microejModule("com.microej.gradle.application:com.microej.gradle.application.gradle.plugin:1.7.0")
microejModule("com.microej.gradle.library:com.microej.gradle.library.gradle.plugin:1.7.0")
microejModule("com.microej.gradle.jse-library:com.microej.gradle.jse-library.gradle.plugin:1.7.0")
microejModule("com.microej.gradle.mock:com.microej.gradle.mock.gradle.plugin:1.7.0")

Step 4 — Configure the Kernel Artifacts

Two artifacts must be provided to application developers:

  • the Stripped Executable, a version of the Kernel binary with all code sections removed. It keeps only the entry symbols and linker metadata required to build .fo Feature files, protecting both MicroEJ and Manufacturer IP from being distributed.

  • the Virtual Device, the simulator image that application developers use to run their applications without physical hardware. It replicates the Kernel environment, including its libraries and APIs.

The Kernel artifacts can be obfuscated (recommended) to prevent reverse engineering of customer’s Kernel managed code. This is optional and the level of obfuscation is configurable by Proguard. Refer to the How To Use Proguard page to configure it.

To include both the Stripped Executable and the Virtual Device of your Kernel project, declare it as dependencies in the packaging/build.gradle.kts file with respectively the Gradle configuration executable and virtualDevice:

dependencies {
    // Fetch and package the Stripped Executable of the given kernel
    "executable"("com.mycompany:my-kernel:1.0.0")

    // Fetch and package the Virtual Device of the given kernel
    "virtualDevice"("com.mycompany:my-kernel:1.0.0")
}

Warning

Make sure that your Kernel project contains the following configuration in its build.gradle.kts file to produce the Stripped Executable and the Virtual Device:

microej {
    produceStrippedExecutableDuringBuild()
    produceVirtualDeviceDuringBuild()
}

Refer to Build a Stripped Executable and Build a Virtual Device pages for details.

Step 5 — Define a Custom EULA (Optional)

The Manufacturer can replace the standard MicroEJ SDK End User License Agreement (EULA) with their own custom EULA. When the MicroEJ Gradle plugin detects a com.microej.gradle:custom-eula module in any repository configured on the user’s project, it substitutes the custom EULA check for the standard SDK EULA check.

If this step is skipped, the standard SDK EULA applies.

The full procedure is described in How To Define a Custom EULA. At a high level, it involves:

  1. Creating a Library module which contains a custom-eula.properties file. This file defines the Gradle system property name, environment variable name, and error message that Application developers will see if they have not accepted the EULA.

  2. Publishing this Library as a Maven artifact with the coordinates com.microej.gradle:custom-eula to a repository accessible to Application developers. Therefore, it should be embedded directly in the Module Repository of the Developer Package, or published in another repository which must be declared in its module-repository.gradle.kts file.

Note

Application developers must accept the custom EULA before any Gradle task can run. The EULA is accepted by setting a Gradle system property or an environment variable as documented by the Manufacturer. Refer to How To Define a Custom EULA for all available acceptance methods.

Step 6 — Deliver the Developer Package

The Developer Package can be generated by building the packaging module. It outputs an archive containing all the configured items in the packaging/build/package folder.

This archive can then be delivered to the Application Developers. It contains everything to start developing Applications on a Kernel (components and documentation). The Application Developer can now unzip the archive, then open the README.md file located in the root folder and follow the instructions.