Build Firmware¶

Prerequisite of this chapter: minimum understanding of MicroEJ Module Manager.

Workspace Build¶

Firmware Build Flow in MicroEJ SDK Workspace¶

Headless Build¶

Runtime Environment¶

A Firmware define a runtime environment which is the set of classes, methods and fields all applications are allowed to use. In most of the cases the runtime environment is an aggregation of several kernel APIs built with module project build-runtime-api skeleton.

<info organisation="myorg" module="mymodule" status="integration"
revision="1.0.0">
   <ea:build organisation="com.is2t.easyant.buildtypes" module="build-runtime-api" revision="2.+">
   <ea:plugin org="com.is2t.easyant.plugins" module="clean-artifacts" revision="2.+" />
   <ea:property name="clean.artifacts.max.keep" value="2" />
   <ea:property name="runtime.api.name" value="RUNTIME"/>
   <ea:property name="runtime.api.version" value="1.0"/>
   </ea:build>
</info>

The runtime.api.name property define the name of the runtime environment (it is required by the build type), and the runtime.api.version property define it version. If the property runtime.api.version is not provided the build type computes it using the revision of the ivy module.

<dependencies>
   <dependency org="com.microej.kernelapi" name="edc" rev="[1.0.4-RC0,1.0.5-RC0[" transitive="false"/>
   <dependency org="com.microej.kernelapi" name="kf" rev="[2.0.1-RC0,2.0.2-RC0[" transitive="false"/>
   <dependency org="com.microej.kernelapi" name="bon" rev="[1.0.4-RC0,1.0.5-RC0[" transitive="false"/>
   <dependency org="com.microej.kernelapi" name="wadapps" rev="[1.2.2-RC0,1.2.3-RC0[" transitive="false"/>
   <dependency org="com.microej.kernelapi" name="components" rev="[1.2.2-RC0,1.2.3-RC0[" transitive="false"/>
</dependencies>

This runtime environment aggregate all classes, methods and fields defined by edc,kf,bon,wadapps,components kernel APIs.

The documentation of a runtime environment is packaged into the Virtual Device as HTML javadoc (Help > MicroEJ Resource Center > Javadoc).

Specify the Runtime Environment of the Firmware¶

While building a firmware, two ways exist to specify the runtime environment:

By using one or more ivy dependencies of kernel API artifacts. In this case we must set properties runtime.api.name and runtime.api.version.
By using the ivy dependency runtimeapi module.

Resident Applications¶

A MicroEJ Sandboxed Application can be dynamically installed from a MicroEJ Forge instance or can be directly linked into the Firmware binary at built-time. In this case, it is called a Resident Application.

The user can specify the Resident Applications in two different ways:

Set the property build-systemapps.dropins.dir to a folder with contains all the resident applications.

Add ivy dependencyy on each resident application:

<dependency org="com.microej.app.wadapps" name="management"
rev="[2.2.2-RC0,3.0.0-RC0[" conf="systemapp->application"/>

All Resident Applications are also available for the Virtual Device, if a resident application should only be available for the Firmware, use an ivy dependency with the ivy configuration systemapp-fw instead of systemapp, like:

<dependency org="com.microej.app.wadapps" name="management" rev="[2.2.2-RC0,3.0.0-RC0[" conf="systemapp-fw->application"/>

Advanced¶

MicroEJ Firmware `module.ivy`¶

The following section describes module description file (module.ivy) generated by the build-firmware-multiapp skeleton.

Ivy info¶

<info organisation="org" module="module" status="integration"
revision="1.0.0">
    <ea:build organisation="com.is2t.easyant.buildtypes" module="build-firmware-multiapp" revision="2.+"/>
    <ea:property name="application.main.class" value="org.Main" />
    <ea:property name="runtime.api.name" value="RUNTIME" />
    <ea:property name="runtime.api.version" value="0.1.0" />
</info>

The property application.main.class is set to the fully qualified name of the main java class. The firmware generated from the skeleton defines its own runtime environment by using ivy dependencies on several kernel API instead of relying on a runtime environment module. As consequence, the runtime.api.name and runtime.api.version properties are specified in the firmware project itself.

Ivy Configurations¶

The build-firmware-multiapp build type requires the following configurations, used to specify the different kind of firmware inputs (see Firmware Input and Output Artifacts) as Ivy dependencies.

<configurations defaultconfmapping="default->default;provided->provided">
    <conf name="default" visibility="public"/>
    <conf name="provided" visibility="public"/>
    <conf name="platform" visibility="public"/>
    <conf name="vdruntime" visibility="public"/>
    <conf name="kernelapi" visibility="private"/>
    <conf name="systemapp" visibility="private"/>
    <conf name="systemapp-fw" visibility="private"/>
</configurations>

The following table lists the different configuration mapping usage where a dependency line is declared:

<dependency org="..." name="..." rev="..." conf="[Configuration Mapping]"/>

Configurations Mapping for `build-firmware-multiapp` Build Type¶
Configuration Mapping	Dependency Kind	Usage
`provided->provided`	Foundation Library (`JAR`)	Expected to be provided by the platform. (e.g. `ej.api.*` module)
`default->default`	Add-On Library (`JAR`)	Embedded in the firmware only, not in the Virtual Device
`vdruntime->default`	Add-On Library (`JAR`)	Embedded in the Virtual Device only, not in the firmware
`default->default;` `vdruntime->default`	Add-On Library (`JAR`)	Embedded in both the firmware and the Virtual Device
`platform->platformDev`	Platform (`JPF`)	Platform dependency used to build the firmware and the Virtual Device. There are other ways to select the platform (see Platform Selection)
`kernelapi->default`	Runtime Environment (`JAR`)	See Runtime Environment
`systemapp->application`	Application (`WPK`)	Linked into both the firmware and the Virtual Device as resident application. There are other ways to select resident applications (see Resident Applications)
`systemapp-fw->application`	Application (`WPK`)	Linked into the firmware only as resident application.

Example of minimal firmware dependencies.

The following example firmware contains one system app (management), and defines an API that contains all types, methods, and fields from edc,kf,wadapps,components.

<dependencies>
    <dependency org="ej.api" name="edc" rev="[1.2.0-RC0,2.0.0-RC0[" conf="provided" />
    <dependency org="ej.api" name="kf" rev="[1.4.0-RC0,2.0.0-RC0[" conf="provided" />
    <dependency org="ej.library.wadapps" name="framework" rev="[1.0.0-RC0,2.0.0-RC0[" />
    <dependency org="com.microej.library.wadapps.kernel" name="common-impl" rev="[3.0.0-RC0,4.0.0-RC0[" />
    <dependency org="com.microej.library.wadapps" name="admin-kf-default" rev="[1.2.0-RC0,2.0.0-RC0[" />
    <!-- Runtime API (set of Kernel API files) -->
    <dependency org="com.microej.kernelapi" name="edc" rev="[1.0.0-RC0,2.0.0-RC0[" conf="kernelapi->default"/>
    <dependency org="com.microej.kernelapi" name="kf" rev="[2.0.0-RC0,3.0.0-RC0[" conf="kernelapi->default"/>
    <dependency org="com.microej.kernelapi" name="wadapps" rev="[1.0.0-RC0,2.0.0-RC0[" conf="kernelapi->default"/>
    <dependency org="com.microej.kernelapi" name="components" rev="[1.0.0-RC0,2.0.0-RC0[" conf="kernelapi->default"/>
    <!-- System apps -->
    <dependency org="com.microej.app.wadapps" name="management"
    rev="[2.2.2-RC0,3.0.0-RC0[" conf="systemapp->application"/>
</dependencies>

Change the set of Properties used to Build a Firmware¶

The build use the file build/common.properties to configure the build process.

Change the Platform used to Build the Firmware and the Virtual Device¶

To build a MicroEJ Firmware and a Virtual Device, a MicroEJ Platform must provided (see Platform Selection section).

Build only a Firmware¶

Set the property skip.build.virtual.device

<ea:property name="skip.build.virtual.device" value="SET" />

Build only a Virtual Device¶

Set the property virtual.device.sim.only

<ea:property name="virtual.device.sim.only" value="SET" />

Build only a Virtual Device with a pre-existing Firmware¶

Copy/Paste the .kpk file into the folder dropins