MicroEJ Module Manager

Introduction

Modern electronic device design involves many parts and teams to collaborate to finally obtain a product to be sold on its market. MicroEJ encourages modular design which involves various stake holders: hardware engineers, UX designers, graphic designers, drivers/BSP engineers, software engineers, etc.

Modular design is a design technique that emphasizes separating the functionality of an application into independent, interchangeable modules. Each module contains everything necessary to execute only one aspect of the desired functionality. In order to have team members collaborate internally within their team and with other teams, MicroEJ provides a powerful modular design concept, with smart module dependencies, controlled by the MicroEJ Module Manager (MMM). MMM frees engineers from the difficult task of computing module dependencies. Engineers specify the bare minimum description of the module requirements.

The following schema introduces the main concepts detailed in this chapter.

MMM Overview

MMM is based on the following tools:

• Apache Ivy (http://ant.apache.org/ivy) for dependencies resolution and module publication;
• Apache EasyAnt (https://ant.apache.org/easyant/history/trunk/reference.html) for module build from source code.

Specification

MMM provides a non ambiguous semantic for dependencies resolution. Please consult the MMM specification available on https://developer.microej.com/packages/documentation/TLT-0831-SPE-MicroEJModuleManager-2.0-E.pdf.

Module Project Skeleton

In MicroEJ SDK, a new MicroEJ module project is created as following:

• Select File > New > Project…,
• Select MicroEJ > MicroEJ Module Project [1],
• Fill the module information (project name, module organization, name and revision),
• Select one of the suggested skeletons depending on the desired module nature,
• Click on Finish.

The project is created and a set of files and directories are generated from the selected skeleton.

Note

When an empty Eclipse project already exists or when the skeleton has to be created within an existing directory, the MicroEJ module is created as following:

• In the Package Explorer, click on the parent project or directory,
• Select File > New > Other…,
• Select EasyAnt > EasyAnt Skeleton.

Module Description File

A module description file is an Ivy configuration file named module.ivy, located at the root of each MicroEJ module project. It describes the module nature (also called build type) and dependencies to other modules.

<ivy-module version="2.0" xmlns:ea="http://www.easyant.org" xmlns:m="http://ant.apache.org/ivy/extra"
                          xmlns:ej="https://developer.microej.com" ej:version="2.0.0">
    <info organisation="[organisation]" module="[name]" status="integration" revision="[version]">
        <ea:build organisation="com.is2t.easyant.buildtypes" module="[buildtype_name]" revision="[buildtype_version]">
            <ea:property name="[buildoption_name]" value="[buildoption_value]"/>
        </ea:build>
    </info>

    <configurations defaultconfmapping="default->default;provided->provided">
        <conf name="default" visibility="public"/>
        <conf name="provided" visibility="public"/>
        <conf name="documentation" visibility="public"/>
        <conf name="source" visibility="public"/>
        <conf name="dist" visibility="public"/>
        <conf name="test" visibility="private"/>
    </configurations>

    <publications>
    </publications>

    <dependencies>
      <dependency org="[dep_organisation]" name="[dep_name]" rev="[dep_version]"/>
    </dependencies>
</ivy-module>

Enable MMM Semantic

The MMM semantic is enabled in a module by adding the MicroEJ XML namespace and the ej:version attribute in the ivy-module node:

<ivy-module xmlns:ej="https://developer.microej.com" ej:version="2.0.0">

Note

Multiple namespaces can be declared in the ivy-module node.

MMM semantic is enabled in the module created with the Module Project Skeleton.

Module Dependency

Module dependencies are added to the dependencies node as follow:

<dependencies>
  <dependency org="[dep_organisation]" name="[dep_name]" rev="[dep_version]"/>
</dependencies>

When no matching rule is specified, the default matching rule is compatible.

Dependency Matching Rule

The following matching rules are specified by MMM:

Name	Range Notation	Semantic
compatible	[M.m.p-RC, (M+1).0.0-RC[	Equal or up to next major version. Default if not set.
equivalent	[M.m.p-RC, M.(m+1).0-RC [	Equal or up to next minor version
greaterOrEqual	[M.m.p-RC, ∞[	Equal or greater versions
perfect	[M.m.p-RC, M.m.(p+1)-RC[	Exact match (strong dependency)

Set the matching rule of a given dependency with ej:match="matching rule". For example:

<dependency org="[dep_organisation]" name="[dep_name]" rev="[dep_version]" ej:match="perfect" />

Dependency Visibility

• A dependency declared public is transitively resolved by upper modules. The default when not set.

• A dependency declared private is only used by the module itself, typically for:

  • Bundling the content into the module
  • Testing the module

The visibility is set by the configurations declared in the configurations node. For example:

<configurations defaultconfmapping="default->default;provided->provided">
    <conf name="[conf_name]" visibility="private"/>
</configurations>

The configuration of a dependency is specified by setting the conf attribute, for example:

<dependency org="[dep_organisation]" name="[dep_name]" rev="[dep_version]" conf="[conf_name]->*" />

Automatic Update Before Resolution

The Easyant plugin ivy-update can be used to automatically update the version (attribute rev) of every module dependencies declared.

<info organisation="[organisation]" module="[name]" status="integration" revision="[version]">
    <ea:plugin org="com.is2t.easyant.plugins" name="ivy-update" revision="1.+" />
</info>

When the plugin is enabled, for each module dependency, MMM will check the version declared in the module file and update it to the highest version available which satisfies the matching rule of the dependency.

Build Options

MMM Build Options can be set with:

<ea:property name="[buildoption_name]" value="[buildoption_value]"/>

The following build options are globally available:

Build Options

Property Name	Description	Default Value
target	Path to the build directory target~.	${basedir}/target~

Refer to the documentation of Module Natures for specific build options.

MicroEJ Module Manager Configuration

By default, when starting an empty workspace, MicroEJ SDK is configured to import dependencies from MicroEJ Central Repository and to publish built modules to a local folder. The repository configuration is stored in a settings file (ivysettings.xml), and the default one is located at $USER_HOME\.microej\microej-ivysettings-[VERSION].xml

Preferences Page

The MMM preferences page is available at Window > Preferences > MicroEJ > Module Manager [1].

MMM Preferences Page

This page allows to configure the following elements:

1. Settings File: the file describing how to connect module repositories. See the settings file section.

2. Options: files declaring MMM options. See the Options section.

3. Use Module repository as Build repository: the settings file for connecting the build repository in place of the one bundled in MicroEJ SDK. This option shall not be enabled by default and is reserved for advanced configuration.

4. Build repository Settings File: the settings file for connecting the build repository in place of the one bundled in MicroEJ SDK. This option is automatically initialized the first time MicroEJ SDK is launched. It shall not be modified by default and is reserved for advanced configuration.

5. Set verbose mode: to enable advanced debug traces when building a module.

6. Runtime JRE: the Java Runtime Environment that executes the build process.

7. Max build history size: the maximum number of previous builds available in Build Module shortcut list:

   

Settings File

The settings file is an XML file that describes how MMM connects local or online module repositories. The file format is described in Apache Ivy documentation.

To configure MMM to a custom settings file (usually from an offline repository):

1. Set Settings file to a custom ivysettings.xml settings file [1],
2. Click on Apply and Close button

If the workspace is not empty, it is recommended to trigger a full resolution and rebuild all the projects using this new repository configuration:

1. Clean caches

   • In the Package Explorer, right-click on a project;
   • Select Ivy > Clean all caches.

2. Resolve projects using the new repository

   To resolve all the workspace projects, click on the Resolve All button in the toolbar:

   

   To only resolve a subset of the workspace projects:

   • In the Package Explorer, select the desired projects,
   • Right-click on a project and select Ivy > Clean all caches.

3. Trigger Add-On Library processors for automatically generated source code

   • Select Project > Clean…,
   • Select Clean all projects,
   • Click on Clean button.

Options

Options can be used to parameterize a module description file or a settings file. Options are declared as key/value pairs in a standard Java properties file, and are expanded using the ${my_property} notation.

A typical usage in a settings file is for extracting repository server credentials, such as HTTP Basic access authentication:

1. Declare options in a properties file

   

2. Register this property file to MMM options

3. Use this option in a settings file

   

A typical usage in a module description file is for factorizing dependency versions across multiple modules projects:

1. Declare an option in a properties file

   

2. Register this property file to MMM options

   

3. Use this option in a module description file

   

Build Kit

The Module Manager build kit is the consistent set of tools and scripts required for building modules.

It is bundled with MicroEJ SDK and can be exported to run in headless mode using the following steps: [1]

• Select File > Export > MicroEJ > Module Manager Build Kit,
• Choose an empty Target directory,
• Click on the Finish button.

Once the build kit is fully exported, the directory content shall look like:

To go further with headless builds, please consult Tool-CommandLineBuild for command line builds, and this tutorial to setup MicroEJ modules build in continuous integration environments).

[1]	(1, 2, 3, 4) If using MicroEJ SDK versions lower than 5.2.0, please refer to the following section.

Former MicroEJ SDK Versions

This section describes MMM configuration elements for MicroEJ SDK versions lower than 5.2.0.

New MicroEJ Module Project

The New MicroEJ Module Project wizard is available at File > New > Project…, EasyAnt > EasyAnt Project.

Preferences Pages

MMM Preferences Pages are located in two dedicated pages. The following pictures show the options mapping using the same options numbers declared in Preferences Page.

Ivy Preferences Page

The Ivy Preferences Page is available at Window > Preferences > Ivy > Settings.

Easyant Preferences Page

The Easyant Preferences Page is available at Window > Preferences > EasyAnt4Eclipse.

Export the Build Kit

• Create an empty directory (e.g. mmm_sdk_[version]_build_kit),
• Locate your SDK installation plugins directory (by default, C:\Program Files\MicroEJ\MicroEJ SDK-[version]\rcp\plugins on Windows OS),
• Open the file com.is2t.eclipse.plugin.easyant4e_[version].jar with an archive manager,
• Extract the directory lib to the target directory,
• Open the file com.is2t.eclipse.plugin.easyant4e.offlinerepo_[version].jar with an archive manager,
• Navigate to directory repositories,
• Extract the file named microej-build-repository.zip for MicroEJ SDK 5.x or is2t_repo.zip for MicroEJ SDK 4.1.x to the target directory.