Build Firmware
Prerequisite of this chapter: minimum understanding of MicroEJ Module Manager.
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 propertiesruntime.api.name
andruntime.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]"/>
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 Change the Platform used to Build the Firmware and the Virtual Device) |
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 firmware and a Virtual Device a platform must be specified. Four different ways are possible to do so:
Use an Ivy dependency.
<dependency org="myorg" name="myname" rev="1.0.0" conf="platform->platformDev" transitive="false"/>
Copy/Paste a platform file into the folder defined by the property
platform-loader.target.platform.dropins
(by default it value isdropins
).Set the property
platform-loader.target.platform.file
.<ea:property name="platform-loader.target.platform.file" value="/path-to-a-platform-file/" />
Set the property
platform-loader.target.platform.dir
.<ea:property name="platform-loader.target.platform.dir" value="/path-to-a-platform-folder/" />
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