Create a Project¶

This chapter explains the different ways to create a new project.

Note

The different project creation systems do not produce exactly the same project content and structure. Especially, the IntelliJ IDEA wizard produces a simple project whereas the Android Studio, Command Line Interface and Eclipse wizards create multi-projects builds. Both structures (single and multi projects) can be used, the recommended one depends on the context (components, size of the project, …). Refer to the official Gradle documentation for more information.

The creation of a project with Android Studio is done as follows:

Click on File > New > Project….
Select Generic > New MicroEJ project.

Project Creation in Android Studio¶

Click on the Next button.
Fill the name of the project in the Name field.
Fill the package name of the project in the Package name field.
Select the location of the project in the Save location field.
Keep the default Android SDK in the Minimum SDK field.
Select Kotlin for the Build configuration language field.

Note

Groovy build script DSL is not officially supported by the SDK, so the project created by the Wizard uses Kotlin regardless of the language selected by the user.

Project Creation in Android Studio¶

Click on Next button.
Fill the group of the artifact to publish in the Group field.
Fill the version of the artifact to publish in the Version field.
Select the module type among Application, Mock and Addon-Library in the drop-down list.
If you selected Application module type, you can check This is a kernel application checkbox if your Application is a Kernel.
Click on Finish button.

Project Creation in Android Studio¶

Change the view from Android to Project in the selectbox at the top of the project’s files tree:

Project View in Android Studio¶

Note

The newly created Gradle project uses Gradle Wrapper with Gradle version 8.2. Refer to the Gradle Wrapper section for more information.

The project created by the wizard is a multi-project with a single subproject (named app). This subproject is either an Application or an Add-On Library, depending on the module type that has been chosen.

Note

By default, Android Studio automatically saves any file change, but requires the user to explicitly trigger the reload of a Gradle project when its configuration has changed. Therefore, when the configuration of a Gradle project has been updated, you have to click on the Sync Now action which appears on the top-right of the editor:

Gradle Project reload in Android Studio¶

You can also configure Android Studio to automatically reload a Gradle project after a change. Refer to the How To Automatically reload a Gradle project section for more information.

Warning

When reloading your Gradle project, the build can fail if the SDK EULA has not been accepted. In that case, you must set the ACCEPT_MICROEJ_SDK_EULA_V3_1B environment variable to YES and restart Android Studio. For more information about SDK EULA, refer to the Licenses chapter.

When the Gradle project has been reloaded, it should compile successfully, without any error. You can then learn how to launch the build of the project, or how to run it on the Simulator in the case of an Application.

The creation of a project with IntelliJ IDEA is done as follows:

Click on File > New > Project….
Select MicroEJ in Generators list on the left panel.
Fill the name of the project in the Name field.
Select the location of the project in the Location field.
Select the module type among Application, Mock and Addon-Library buttons.
If you selected Application module type, you can check This is a kernel application checkbox if your Application is a Kernel.
Fill the version of the artifact to publish in the Version field.
Fill the group of the artifact to publish in the Group field.
Fill the name of the artifact to publish in the Artifact field.
Select the JVM used by Gradle in the JDK combobox.
Check the Add sample code checkbox.
Click on Create button.

Project Creation in IntelliJ IDEA¶

Note

The Gradle project created by the wizard uses Gradle Wrapper with Gradle version 8.5. Refer to the Gradle Wrapper section for more information.

Note

By default, IntelliJ IDEA automatically saves any file change, but requires the user to explicitly trigger the reload of a Gradle project when its configuration has changed. Therefore, when the configuration of a Gradle project has been updated, you have to click on the reload icon button which appears on the right of the editor:

Gradle Project reload in IntelliJ IDEA¶

You can also configure IntelliJ IDEA to automatically reload a Gradle project after a change. Refer to the How To Automatically reload a Gradle project section for more information.

Warning

When reloading your Gradle project, the build can fail if the SDK EULA has not been accepted. In that case, you must set the ACCEPT_MICROEJ_SDK_EULA_V3_1B environment variable to YES and restart IntelliJ IDEA. For more information about SDK EULA, refer to the Licenses chapter.

When the Gradle project is loaded, it should compile successfully, without any error. You can then learn how to launch the build of the project, or how to run it on the Simulator in the case of an Application.

The creation of a project with Eclipse is done as follows:

Click on File > New > Project….
Select the project type MicroEJ > MicroEJ Application Project, MicroEJ Mock or MicroEJ Add-onLibrary Project and click on the Next button.

Project Type Selection in Eclipse¶

Fill the name of the project in the Name field, for example My Project.
Fill the group of the artifact to publish in the Organization field.
Fill the name of the artifact to publish in the Module field.
Fill the version of the artifact to publish in the Revision field.
If you selected Application module type, you can check This is a kernel application checkbox if your Application is a Kernel.
Click on Finish button.

Application Creation in Eclipse¶

Note

The Gradle project created by the wizard uses Gradle Wrapper with Gradle version 8.5. Refer to the Gradle Wrapper section for more information.

Warning

When reloading your Gradle project, the build can fail if the SDK EULA has not been accepted. In that case, you must set the ACCEPT_MICROEJ_SDK_EULA_V3_1B environment variable to YES and restart Eclipse. For more information about SDK EULA, refer to the Licenses chapter.

When the Gradle project is loaded, it should compile successfully, without any error. You can then learn how to launch the build of the project, or how to run it on the Simulator in the case of an Application.

The creation of a project can be done via the command line interface via the Gradle init task. This task guides you through multiple steps to configure and select the project template to use. Refer to the official documentation for the full list of templates and options.

In order to create a MicroEJ project, the best way is to use the application template:

In a new empty directory, execute the command gradle init.
Select the application project type.
Select the Java implementation language.
For the step Generate multiple subprojects for application?, select no.
Select build script DSL Kotlin.

Note

The SDK uses Kotlin as the default Gradle build script DSL. The use of the Groovy build script DSL is still possible but not officially supported.

For the test framework, select JUnit 4.
Choose the name of the project (defaults to the name of the parent directory).
Choose the package name for the source files.
For the target version of Java, select 7.
Decide if you want to use Gradle new APIs and behavior in your build script. If you are new to Gradle, choose no.

Note

These steps are the ones proposed when creating a project with Gradle 8.2.1. Depending on the Gradle version used, the steps to create a project can be slightly different.

The created project is a multi-project build containing a root project and a single subproject (named app). The app subproject is a standard Java Application project (Gradle java plugin), so it must be updated to be a MicroEJ project:

Open the project in your favorite editor.
Open the app/build.gradle.kts file.
Erase its whole content.
Configure the project depending on the module nature you want to build.
Declare the dependencies required by your project in the dependencies block. For example:
```
dependencies {
    implementation("ej.api:edc:1.3.5")
}
```
Delete the test class in the folder app/src/test/java.

Configure a Project¶

The SDK allows to build several types of modules. Each type has its own Gradle plugin and configuration options. Refer to the module type you want to build to configure your project:

Application
Add-On Library
Mock
J2SE Library

Application Project¶

Add the com.microej.gradle.application plugin in the build.gradle.kts file:
```
plugins {
    id("com.microej.gradle.application") version "0.16.0"
}
```
Note

The java plugin must not be added since it is automatically applied by the MicroEJ plugin.
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, for example:
```
microej {
  applicationEntryPoint = "com.mycompany.Main"
}
```

Refer to the page Module Natures for a complete list of the available MicroEJ natures and their corresponding plugins.

Add-On Library Project¶

Add the com.microej.gradle.addon-library plugin in the build script:
```
plugins {
    id("com.microej.gradle.addon-library") version "0.16.0"
}
```
Note

The java plugin must not be added since it is automatically applied by the MicroEJ plugin.

Refer to the page Module Natures for a complete list of the available MicroEJ natures and their corresponding plugins.

Mock¶

Add the com.microej.gradle.mock plugin in the build script:
```
plugins {
    id("com.microej.gradle.mock") version "0.16.0"
}
```
Note

The java plugin must not be added since it is automatically applied by the MicroEJ plugin.

Refer to the page Module Natures for a complete list of the available MicroEJ natures and their corresponding plugins.

J2SE Library Project¶

Add the com.microej.gradle.j2se-library plugin in the build script:
```
plugins {
    id("com.microej.gradle.j2se-library") version "0.16.0"
}
```
Note

The java plugin must not be added since it is automatically applied by the MicroEJ plugin.

Refer to the page Module Natures for a complete list of the available MicroEJ natures and their corresponding plugins.

Create a subproject in an existing project¶

This section explains the different ways to add a module to an existing project.

Warning

If you want to add a MicroEJ module to a non MicroEJ project, for example an Android project, you must configure the repositories before creating the module. If the repositories used by your project are centralized in the settings.gradle.kts file of the project, the MicroEJ repositories defined in this file must be added to your settings.gradle.kts file.

The creation of a module with Android Studio is done as follows:

Click on File > New > New Module….
Select MicroEJ Module in Templates list on the left panel.
Fill the name of the module in the Name field.
Fill the group of the artifact to publish in the Group field.
Fill the version of the artifact to publish in the Version field.
Select the module type among Application and Addon-Library buttons.
If you selected Application module type, you can check This is a kernel application checkbox if your Application is a Kernel.
Click on Finish button.

Module Creation in Android Studio¶

The creation of a module with IntelliJ IDEA is done as follows:

Click on File > New > Module….
Select MicroEJ in Generators list on the left panel.
Fill the name of the module in the Name field.
Select the location of the module in the Location field.
Select the module type among Application and Addon-Library buttons.
If you selected Application module type, you can check This is a kernel application checkbox if your Application is a Kernel.
Fill the version of the artifact to publish in the Version field.
Fill the group of the artifact to publish in the Group field.
Fill the name of the artifact to publish in the Artifact field.
Select the JVM used by Gradle in the JDK combobox.
Check the Add sample code checkbox.
Click on Create button.

Module Creation in IntelliJ IDEA¶

Include the module to your project by adding the following line to the settings.gradle.kts file of the project:
```
include("<module_name>")
```
Right-click on the module name in the Gradle tasks view and click on Unlink Gradle Project.
Reload of a Gradle project by clicking on the reload icon button which appears on the right of the editor:

Gradle Project reload in IntelliJ IDEA¶

The creation of a module with Eclipse is done as follows:

Right-click on your project and click on New > Folder.
Select your project as parent folder.
Fill the name of the module in the Folder name field.
Click on Finish button.

Module Creation in Eclipse¶

Right-click on your newly created folder and click on New > File.
Enter build.gradle.kts in the File name field.
Click on Finish button and open the build.gradle.kts file.
Add the MicroEJ plugin, depending on the module nature you want to build, for example for an Add-On Library:
```
plugins {
    id("com.microej.gradle.addon-library") version "0.16.0"
}
```
or for an Application:
```
plugins {
    id("com.microej.gradle.application") version "0.16.0"
}
```
Refer to the page Module Natures for a complete list of the available MicroEJ natures and their corresponding plugins.
Declare the dependencies required by your project in the dependencies block. For example:
```
dependencies {
    implementation("ej.api:edc:1.3.5")
}
```
Open the settings.gradle.kts file of your project and add the following content:
```
include("<module_name>")
```

Note

By default, Eclipse requires the user to explicitly trigger the reload of a Gradle project when its content has changed. Therefore, when the content of a Gradle project has been updated, you have to right-click on the project, then click on Gradle and Refresh Gradle Project:

Gradle Project reload in Eclipse¶

You can also configure Eclipse to automatically reload a Gradle project after a change. Refer to the How To Automatically reload a Gradle project section for more information.

Right-click on the newly created module and click on New > Source Folder.
Enter src/main/java in the Folder name field.
Click on Finish button.

Source Folder Creation in Eclipse¶

Follow the same steps to create the src/main/resources, src/test/java and src/test/resources folders.

Gradle Wrapper¶

It is recommended to use the Gradle Wrapper to execute a build. The Wrapper is a script that ensures that the required version of Gradle is downloaded and used during the build of a project.

When creating a project following one of the project creation systems described in the Create a Project section, the Wrapper files are automatically generated in the gradle/wrapper folder of the project. It is also possible to add the Wrapper to an existing project by executing the wrapper task:

gradle wrapper

The Gradle version used by the project can then be updated in the gradle/wrapper/gradle-wrapper.properties file. The SDK requires Gradle 8.0.2 or higher:

distributionUrl=https\://services.gradle.org/distributions/gradle-8.0.2-bin.zip

To use the Wrapper during a build, use gradlew or ./gradlew depending on your OS instead of gradle in the command line:

gradlew build

In the following chapters of the documentation, the Linux command ./gradlew is used in all examples to execute a build.

Refer to the official Gradle documentation for more information about the Wrapper.