Project Setup

This chapter will guide you through the process of creating a project for having an application compatible with both Android and MicroEJ VEE.

The recommended project structure to get started is to have a basic multi-project build that contains a root project and two subprojects: one subproject for the Android/Wear OS application and one subproject for the MicroEJ Application. The MicroEJ Application defines code that will run on both MicroEJ VEE and Android, while the Android application includes wrapper code and logic specific to Android.

What follows is the directory and file structure of a typical project:

├── android-app/
│   ├── src
│   ├── microej.properties       # MicroEJ Application Options for Android/Wear OS
│   └── build.gradle.kts
├── microej-app/
│   ├── src
│   ├── configuration/
│   |    └── common.properties   # MicroEJ Application Options for MicroEJ VEE
│   └── build.gradle.kts
├── build.gradle.kts
└── settings.gradle.kts

Create or Import an Android project

The Android documentation covers the process of creating apps for diverse form factors, including smartphones and wearable devices. Read Create a Project and follow the guidelines before proceeding. If you are creating a project from scratch, we recommend using the Empty Activity template.

Note

The project template in Android Studio defines a default repositories configuration in the settings.gradle.kts file of the project like below:

pluginManagement {
   repositories {
      google()
      mavenCentral()
      gradlePluginPortal()
   }
}
dependencyResolutionManagement {
   repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
   repositories {
      google()
      mavenCentral()
   }
}

Please note that this will override the repositories configuration defined during the installation process, based on Gradle initialization scripts. Set the configuration according to your preference, but we suggest removing these lines at first from the settings file to get started.

Assuming that a Gradle project with an Android application is now opened in Android Studio, do the following:

  • Open the build.gradle.kts file at the root of the project.

  • Add these lines to the plugins block:

    id("com.microej.gradle.application") version "0.16.0" apply false
id("com.microej.android.gradle.plugins.android") version "0.3.6" apply false

Create or Import a MicroEJ Application

The next step is adding the module that contains the MicroEJ Application to the Gradle project.

  • Click on File > New > New Module….
  • Select Java or Kotlin Library.
  • Set the name of the module in the Library Name field.
  • Set the package name of the module in the Package name field.
  • Enter a name for the main Java class of the application in the Class name field.
  • Select the language Java in the Language field.
  • Select Kotlin DSL in the Build configuration language field.
  • Click on Finish.

The module created by Android Studio is a standard Java module (Gradle java-library plugin). The build.gradle.kts file has to be updated to make it a MicroEJ Application module:

  • Open the build.gradle.kts file.

  • Erase its whole content.

  • Add the com.microej.gradle.application plugin in the build.gradle.kts file:

    plugins {
   id("com.microej.gradle.application")
}

  • Add the following microej block in the build.gradle.kts file:

    microej {
   applicationEntryPoint = "com.mycompany.Main"
}

    where the property applicationEntryPoint is set to the Full Qualified Name of the main class of the application. This class must define a main() method and is the entry point of the application.

  • Declare the dependencies required by your application in the dependencies block of the build.gradle.kts file. The EDC library is always required in the build path of an Application project, as it defines the minimal runtime environment for embedded devices:

    dependencies {
    implementation("ej.api:edc:1.3.5")
}

  • Set the microejConflictResolutionRulesEnabled property to false in the build.gradle.kts file:

    microej {
   microejConflictResolutionRulesEnabled = false
   ...
}

    Note

    The MicroEJ Gradle plugin comes with additional conflict resolution rules compared to Gradle’s default behavior. This can make the build fail when working with Android dependencies, so it is recommended to use Gradle’s default conflict management in this case. These extra rules can be disabled by setting the microejConflictResolutionRulesEnabled property to false in the microej configuration block. Read Manage Resolution Conflicts for more details.

  • Ensure that the Gradle settings file includes the Android and MicroEJ modules, like in this example:

    include(":android-app")
include(":microej-app")

  • To synchronize your project files, select Sync Now from the notification bar that appears after making changes.

When the Gradle project has been reloaded, it should compile successfully, without any error.

Configure the Android Application

The next steps show how to configure the Android or Wear OS application to declare the MicroEJ Application.

  • Open the build.gradle.kts file of the Android application.

  • Add the com.microej.android.gradle.plugins.android plugin:

    plugins {
   id("com.android.application")
   id("com.microej.android.gradle.plugins.android")
   ...
}

  • Add a dependency to the MicroEJ support library depending on the target (Android or Wear OS).

dependencies {
   implementation("com.microej.android.support:microej-application:2.0.1")
   ...
}

The support library microej-application allows running a MicroEJ Application in an Android Activity using the MicroEJ support engine.

  • Add a dependency to the MicroEJ Application using the microejApp configuration, for example:

    dependencies {
   microejApp(project(":microej-app"))
   ...
}

    where microej-app is the name of the subproject that contains the MicroEJ Application.

  • Add a dependency to a VEE Port, for example:

    dependencies {
   microejVee("com.mycompany:veeport:1.0.0")
   ...
}

    There are multiple options for providing a VEE Port in your project. Read Select a VEE Port to explore the available options.

    Note

    It is required to select a VEE Port that’s configured to build MicroEJ Applications for Android. Read the VEE Port section to learn how to configure a VEE Port for this purpose.

  • Add a file named microej.properties at the root of the Android application. This file sets the MicroEJ Application Options when running on Android. It is similar in principle to defining Application Options for the embedded device. Depending on the target device (Android or embedded device), the content may differ.

  • Select Sync Now from the notification bar to synchronize your project files.

Start the MicroEJ Application

The final step involves calling the entry point of the MicroEJ Application from within the Android or Wear OS application.

Assuming that the Android application declares an activity in the AndroidManifest.xml:

  • Open the corresponding activity Java/Kotlin file.
  • Make MicroEJActivity the superclass of this class.
  • Override the method getApplicationMainClass() and make it return the Full Qualified Name of the main class of the MicroEJ Application.

This is an example of a simple activity:

class MainActivity : MicroEJActivity() {
   override fun getApplicationMainClass(): String {
      return "com.mycompany.Main";
   }
}

When the activity is created, it instantiates the main class of the MicroEJ Application and invokes its main() method.

Select Sync Now from the notification bar to synchronize your project files.

Run on MicroEJ VEE and Android

The application can now be deployed to both MicroEJ VEE and Android environments.

The deployment of an application designed to use the Android Compatibility Kit has nothing specific compared to other MicroEJ or Android applications. This means that you can refer to the dedicated documentation for this matter: