Migration Notes

Note

When updating the plugin version, it is recommended to perform a clean on your project(s). For multi-projects, run the clean command on the root project.

From 1.8.0 to 1.9.0

This section applies if SDK 6 1.9.0 is used on a project that was created using SDK 6 1.8.0 or lower.

Deprecations

Stack Trace Reader Configuration

The Stack Trace Reader configuration can now be done in a dedicated block of the microej extension:

microej {
    stackTraceReader {
        connectionMode = "file"
        filePath = "/path/to/input/file"
        fileResultPath = "/path/to/output/file"
    }
}

The previous properties are now deprecated and will be removed in the next major version.

Refer to the Configure section for the list of the available options.

Declaring KF Definition Files

Declaring KF Definition Files (*.kf files) is deprecated and will no longer be supported in the next major version. These files are automatically generated and their properties can be customized in the microej extension:

microej {
    applicationEntryPoint = "com.mycompany.MyFeature"
    applicationName = "myApp"
    applicationVersion = "0.1.0"
}

Ivy Descriptor Publication

The Gradle property enable.ivy.descriptor.default is deprecated and will be replaced by a new property in the next major version.

The withIvyDescriptor() method of the microej extension is deprecated and will be removed in the next major version.

Refer to How To Disable Ivy Descriptor Publication for more information.

Gradle and JDK Versions

Gradle versions lower than 9.0, and running a build with a JDK lower than 21, are deprecated and will no longer be supported in the next major version. When a build uses one of them, the SDK lists it at the end of the build, for example:

Deprecated MicroEJ SDK features were used in this build, making it incompatible with its next major version:
- Gradle 8.6 is used. Gradle versions lower than 9.0 will no longer be supported in the next major version. Update the version in the gradle/wrapper/gradle-wrapper.properties file to make it compatible.
- JDK 17 is used to run the build. JDK versions lower than 21 will no longer be supported in the next major version. Run the build with JDK 21 or higher to make it compatible.

To make the project compatible:

Upgrade the Gradle Wrapper version of the project to Gradle 9.0 or higher. Check the SDK and Gradle Compatibility table.
Run the build with a JDK 21 or higher, as described in Check your JDK version.

Publication of the Executable and the Virtual Device of a Kernel Project

When an Application depends on a Kernel defined as a project dependency (microejVee(project(":kernel"))), the Application project registers the Executable and the Virtual Device of the Kernel for publication on its behalf. This behavior is deprecated and will no longer be done in the next major version. A warning is now displayed during the build when the Kernel project does not request the production of these artifacts itself.

The Kernel project must call produceExecutableDuringBuild() and produceVirtualDeviceDuringBuild() in the microej configuration block of its build.gradle.kts file:

microej {
   produceExecutableDuringBuild()
   produceVirtualDeviceDuringBuild()
}

Refer to the Trigger Executable Build by Default and Trigger Virtual Device Build by Default sections for more information.

MicroejExtension Class

The com.microej.gradle.plugins.MicroejExtension class is deprecated. The microej block of the build scripts is not affected: only a build script that references the class explicitly, for example with an import or a configure<MicroejExtension> call, will have to be updated in the next major version.

VEE Declaration in Library and Testsuite Projects

In a Library project or a Testsuite project, the VEE is only used to execute the tests. Declaring it with the microejVee configuration is deprecated and will no longer be supported in the next major version. When migrating to the next major version, declare the VEE with the testMicroejVee configuration instead (refer to Configure the VEE).

Testsuite Verbose Properties

The microej.testsuite.verbose and microej.testsuite.verbose.level properties are deprecated and will be ignored in the next major version. When a build sets one of them, the SDK lists it at the end of the build, for example:

Deprecated MicroEJ SDK features were used in this build, making it incompatible with its next major version:
- The 'microej.testsuite.verbose.level' property will be ignored in the next major version. Set the Gradle log level instead (for example '--info').

To make the project compatible, remove these properties and set the Gradle log level instead, for example:

./gradlew test --info

Refer to the Configure the Testsuite Engine section for more information.

VEE Transitivity

The VEE transitivity will be enabled by default in the next major version. The transitive dependencies of the VEE Port will then be added to the compile classpath and runtime classpath of the project. When a project declares a VEE and does not set the feature.vee.transitivity.enabled property to true or false, the SDK warns at the end of the build.

To prepare the project for the next major version, set the feature.vee.transitivity.enabled property to true in the gradle.properties file of the project, and check that the project builds. Refer to Resolve a VEE Port transitively for more information.

To keep the current behavior, set the property to false. This is required when the VEE Port is built with SDK 6 1.4.0 or lower, because such a VEE Port is not compatible with the VEE transitivity. Update the VEE Port to SDK 6 1.5.0 or higher before enabling the VEE transitivity.

From 1.6.0 to 1.7.0

This section applies if SDK 6 1.7.0 is used on a project that was created using SDK 6 1.6.0 or lower.

New SDK EULA

A new SDK EULA must be approved before using the SDK (version 4.1-A). Refer to SDK EULA Acceptation page to learn how to approve it.

From 1.5.0 to 1.6.0

The Kotlin version used to compile the SDK has been upgraded to support Gradle 9. If your project uses Kotlin you may have such compilation errors:

plugins-1.6.0-SNAPSHOT.jar!/META-INF/plugins.kotlin_moduleModule was compiled with an incompatible version of Kotlin. The binary version of its metadata is 2.3.0, expected version is 1.9.0.

To fix this error you must either:

upgrade to Gradle 9. Check this page to get the latest available version, then update the gradle/wrapper/gradle-wrapper.properties file accordingly.
upgrade the Kotlin Gradle plugin used in your project to version 2.3.0 minimum, by adding this line in the plugins block:
```
kotlin("jvm") version "2.3.0"
```

From 1.3.1 to 1.4.0

The plugin com.microej.gradle.addon-library has been renamed to com.microej.gradle.library. The previous name is still supported but it is deprecated and will be removed in the next major version. It is recommended to update your project now.

From 1.0.0 to 1.1.0

The following plugins have been removed:

plugin com.microej.gradle.j2se-library, replaced by com.microej.gradle.jse-library.
plugin com.microej.gradle.runtime-api, replaced by com.microej.gradle.runtime-environment.

From 0.19.0 to 0.20.0

This section applies if SDK 6 0.20.0 is used on a project that was created using SDK 6 0.19.0 or lower.

Minimum Gradle version

The minimum required version of Gradle is now 8.6.. Upgrade the Gradle Wrapper version of your project.

New SDK EULA

A new SDK EULA must be approved before using the SDK (version 3.1-C). Refer to SDK EULA Acceptation page to learn how to approve it.

Plugins and Configurations renaming

The following plugins and configurations have been renamed:

plugin com.microej.gradle.j2se-library to com.microej.gradle.jse-library.
plugin com.microej.gradle.runtime-api to com.microej.gradle.runtime-environment.
configuration microejRuntimeApi to microejRuntimeEnvironment.

The previous plugins and configurations are still supported but are deprecated and will be removed in the next major version. It is recommended to update your project now.

Virtual Device Build

The Virtual Device of an Application is not built by default anymore when calling the build task. You can call the buildVirtualDevice task to build it, or add the following code in your build.gradle.kts file to continue to build it when calling the build task:

microej {
   produceVirtualDeviceDuringBuild()
}

From 0.15.0 to 0.16.0

This section applies if SDK 6 0.16.0 is used on a project that was created using SDK 6 0.15.0 or lower.

Unification of Application EntryPoint

The creation of a Sandboxed Application and a Standalone Application have been unified. To create an Application, the following steps must be done:

Create the Java main class in the src/main/java folder.
Define the property applicationEntryPoint in the microej configuration block of the build.gradle.kts file. It must be set to the Full Qualified Name of the Application main class:
```
microej {
   applicationEntryPoint = "com.mycompany.Main"
}
```
Define a VEE (VEE Port or Kernel) by declaring a dependency in the build.gradle.kts file:
```
dependencies {
   microejVee("com.mycompany:myVee:1.0.0")
}
```

If your Application requires the use of advanced features, you must create a Feature class, for example:

package com.mycompany;

import ej.kf.FeatureEntryPoint;

public class MyFeature implements FeatureEntryPoint {

  @Override
  public void start() {
    System.out.println("Feature MyFeature started!");
  }

  @Override
  public void stop() {
    System.out.println("Feature MyFeature stopped!");
  }
}

and set the property applicationEntryPoint to the Full Qualified Name of the Feature class:

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

Testsuite Execution

When upgrading from 0.15.0 to an higher version (up to 1.0.0), you may encounter the following error when executing a testsuite:

Preparing the execution of tests with the MicroEJ JUnit test engine

org.junit.platform.commons.JUnitException: TestEngine with ID 'microej-junit-test-engine' failed to execute tests
   at org.junit.platform.launcher.core.EngineExecutionOrchestrator.execute(EngineExecutionOrchestrator.java:113)
   at org.junit.platform.launcher.core.EngineExecutionOrchestrator.execute(EngineExecutionOrchestrator.java:88)
   ...
Caused by: com.microej.testengine.TestEngineException: More than one VEE Port have been provided to run the testsuite
   at com.microej.testengine.MicroejTestEngine.execute(MicroejTestEngine.java:203)
   at org.junit.platform.launcher.core.EngineExecutionOrchestrator.execute(EngineExecutionOrchestrator.java:107)
   ... 29 more

Execute the clean task before executing the testsuite to solve this issue.

From 0.14.0 to 0.15.0

This section applies if SDK 6 0.15.0 is used on a project that was created using SDK 6 0.14.0 or lower.

Unification of VEE dependency declaration

The microejVeePort configuration, used to define a VEE Port, and the microejKernel configuration, used to define a Kernel, have been unified into the microejVee configuration.

To use a VEE Port or a Kernel published in an artifact repository, declare a Module dependency in the build.gradle.kts file:
```
dependencies {
   microejVee("com.mycompany:myVee:1.0.0")
}
```
To use a VEE Port directory available locally, declare a file dependency in the build.gradle.kts file:
```
dependencies {
   microejVee(files("C:\\path\\to\\my\\veePort\\source"))
}
```
To use a VEE Port archive available locally, declare a file dependency in the build.gradle.kts file:
```
dependencies {
   microejVee(files("C:\\path\\to\\my\\veePort\\file.zip"))
}
```

To use a Kernel Virtual Device and Executable available locally, declare a file dependency in the build.gradle.kts:

dependencies {
   microejVee(files("C:\\path\\to\\my\\kernel\\executable.out", "C:\\path\\to\\my\\kernel\\virtual\\device"))
}

From 0.11.1 to 0.12.0

This section applies if SDK 6 0.12.0 is used on a project that was created using SDK 6 0.11.1 or lower.

Use of File Dependencies to Define a Local VEE Port or a Kernel Executable

The veePortPath and the kernelFile properties have been replaced by file dependencies.

To use a VEE Port archive available locally, declare a file dependency in the build.gradle.kts file, with the microejVeePort configuration:
```
dependencies {
   microejVeePort(files("C:\\path\\to\\my\\veePort\\file.zip"))
}
```
To use a VEE Port directory available locally, declare a file dependency in the build.gradle.kts file, with the microejVeePort configuration:
```
dependencies {
   microejVeePort(files("C:\\path\\to\\my\\veePort\\source"))
}
```
To use a kernel Virtual Device and Executable available locally, declare a file dependency in the build.gradle.kts file, with the microejKernel configuration:
```
dependencies {
   microejKernel(files("C:\\path\\to\\my\\kernel\\executable.out", "C:\\path\\to\\my\\kernel\\virtual\\device"))
}
```

From 0.10.0 to 0.11.0

This section applies if SDK 6 0.11.0 is used on a project that was created using SDK 6 0.10.0 or lower.

Gradle mechanism usage for Multiple VEE Ports Support

Using multiple VEE Ports in a project uses Gradle mechanism now instead of relying on in-house feature. This implies: - the veePortPaths property has been renamed to veePortPath and accepts a String value:

microej {
   veePortPath = "C:\\path\\to\\my\\veePort\\source"
}

the kernelFiles property has been renamed to kernelFile and accepts a String value:
```
microej {
   kernelFile = "C:\\path\\to\\my\\kernel\\file"
}
```

Refer to the How To Build an Executable With Multiple VEE Ports section to learn how to support multiple VEE Ports using the Gradle mechanisms.

From 0.8.0 to 0.9.0

This section applies if SDK 6 0.9.0 is used on a project that was created using SDK 6 0.8.0 or lower.

Merge of the veePortDirs and veePortFiles properties

The build properties veePortDirs and veePortFiles have been merged into a single property veePortPaths. To define a local VEE Port, set the build property veePortPaths in the microej configuration block to the path of the VEE Port file (.zip or .vde) or to the source folder of the VEE Port:

microej {
  veePortPaths = listOf("C:\\path\\to\\my\\veePort\\source")
}

The veePortPaths property is defined as a list in order to provide multiple VEE Port files or source folders if it is needed:

microej {
  veePortPaths = listOf("C:\\path\\to\\my\\veePort1\\source", "C:\\path\\to\\my\\veePort2\\file.zip")
}