Standalone Application

Introduction

A Standalone Application is a Java Application directly linked to the C code to produce an Executable. Such an application must define a main entry point (i.e., a class containing a public static void main(String[]) method).

The following figure shows the general process of building a Standalone Application to an Executable.

Standalone Application Link Flow

Standalone Application Link Flow

Standalone Application Options

To run a Standalone Application on a VEE Port, a set of options must be defined. Options can be of different types:

  • Memory Allocation options (e.g., set the Java Heap size). These options are usually called link-time options.
  • Simulator & Debug options (e.g., enable periodic Java Heap dump).
  • Deployment options (e.g., copy microejapp.o to a suitable BSP location).
  • Foundation Library specific options (e.g., embed UTF-8 encoding).

The following section describes options provided by the latest Architecture version. Please consult the appropriate Pack(s) documentation for options related to other Foundation Libraries (MicroUI, NET, SSL, FS, …) integrated to your VEE Port.

Notice that some options may not be supported by your VEE Port, in the following cases:

  • Option is specific to the Core Engine capability (tiny/mono/multi).
  • Option is specific to the target (Core Engine or Simulator).
  • Option has been introduced in a newer Architecture version.

Defining an Option with SDK 6

With the SDK 6, the Applications options can be defined in a properties file located in the configuration folder of the project. Usually, the options are defined in a file named common.properties, but all properties files located in this folder are loaded, no matter what their name is.

To set an option in a properties file, open the file in a text editor and add a line to set the desired option to the desired value, for example:

soar.generate.classnames=false

Defining an Option with SDK 5 or lower

With the SDK 5 or lower, a Standalone Application option can be defined either from a launcher or from a properties file. It is also possible to use both together. Each MicroEJ Architecture and MicroEJ Pack option comes with a default value, which is used if the option has not been set by the user.

Using a Launcher

To set an option in a launcher, perform the following steps:

  1. In the SDK, select Run > Run Configurations… menu,
  2. Select the launcher of the application under MicroEJ Application or create a new one,
  3. Select the Configuration tab,
  4. Find the desired option and set it to the desired value. If the option does not appear in the page, there are two cases: - the option has been introduced in a newer Architecture version, - the option is an advanced option. It is set using a system property in the JRE Tab. See the JRE Tab section for more details.

It is recommended to index the launcher configuration to your version control system. To export launcher options to the filesystem, perform the following steps:

  1. Select the Common tab,
  2. Select the Shared file: option and browse the desired export folder,
  3. Press the Apply button. A file named [launcher_configuration_name].launch is generated in the export folder.

Using a Properties File

Options can be also be defined in properties files.

When a Standalone Application is built using the firmware-singleapp skeleton, options are loaded from properties files located in the build folder at the root of the project.

The properties files are loaded in the following order:

  1. Every file matching build/sim/*.properties, for Simulator options only (Virtual Device build). These files are optional.
  2. Every file matching build/emb/*.properties, for Device options only (Firmware build). These files are optional.
  3. Every file matching build/*.properties, both for Simulator and Device options. At least one file is required.

Usually, the build folder contains a single file named common.properties.

In case an option is defined in multiple properties files, the option of the first loaded file is taken into account and the same option defined in the other files is ignored (a loaded option cannot be overridden).

The figure below shows the expected tree of the build folder:

Build Options Folder

Build Options Folder

It is recommended to index the properties files to your version control system.

To set an option in a properties file, open the file in a text editor and add a line to set the desired option to the desired value. For example: soar.generate.classnames=false.

To use the options declared in properties files in a launcher, perform the following steps:

  1. In the SDK, select Run > Run Configurations…,
  2. Select the launcher of the application,
  3. Select the Execution tab,
  4. Under Option Files, press the Add… button,
  5. Browse the sim.properties file for Simulator or the emb.properties file for Device (if any) and press Open button,
  6. Add the common.properties file and press the Open button.

Note

An option set in a properties file can not be modified in the Configuration tab. Options are loaded in the order the properties files are added (you can use Up and Down buttons to change the file order). In Configuration tab, hovering the pointer over an option field will show the location of the properties file that defines the option.

Generating a Properties File

In order to export options defined in a .launch file to a properties file, perform the following steps:

  1. Select the [launcher_configuration_name].launch file,
  2. Select File > Export > MicroEJ > Launcher as Properties File,
  3. Browse the desired output .properties file,
  4. Press the Finish button.

Warning

The Simulator uses some system properties to configure internal memory limits. See Group: Advanced Simulation Options for more information.

Category: Runtime

../_images/img11.png

Group: Types

Option(checkbox): Embed all type names

Option Name: soar.generate.classnames

Default value: true

Description:

Embed the name of all types. When this option is disabled, only names of declared required types are embedded.

Group: Assertions

Option(checkbox): Execute assertions on Simulator

Option Name: core.assertions.sim.enabled

Default value: false

Description:

When this option is enabled, assert statements are executed. Please note that the executed code may produce side effects or throw java.lang.AssertionError.

Option(checkbox): Execute assertions on Device

Option Name: core.assertions.emb.enabled

Default value: false

Description:

When this option is enabled, assert statements are executed. Please note that the executed code may produce side effects or throw java.lang.AssertionError.

Group: Trace

Option(checkbox): Enable execution traces

Option Name: core.trace.enabled

Default value: false

Option(checkbox): Start execution traces automatically

Option Name: core.trace.autostart

Default value: false

Category: Memory

../_images/img21.png

Group: Heaps

Option(text): Java heap size (in bytes)

Option Name: core.memory.javaheap.size

Default value: 65536

Description:

Specifies the Java heap size in bytes.

A Java heap contains live Java objects. An OutOfMemory error can occur if the heap is too small.

Option(text): Immortal heap size (in bytes)

Option Name: core.memory.immortal.size

Default value: 4096

Description:

Specifies the Immortal heap size in bytes.

The Immortal heap contains allocated Immortal objects. An OutOfMemory error can occur if the heap is too small.

Group: Threads

Description:

This group allows the configuration of application and library thread(s). A thread needs a stack to run. This stack is allocated from a pool and this pool contains several blocks. Each block has the same size. At thread startup the thread uses only one block for its stack. When the first block is full it uses another block. The maximum number of blocks per thread must be specified. When the maximum number of blocks for a thread is reached or when there is no free block in the pool, a StackOverflow error is thrown. When a thread terminates all associated blocks are freed. These blocks can then be used by other threads.

Option(text): Number of threads

Option Name: core.memory.threads.size

Default value: 5

Description:

Specifies the number of threads the application will be able to use at the same time.

Option(text): Number of blocks in pool

Option Name: core.memory.threads.pool.size

Default value: 15

Description:

Specifies the number of blocks in the stacks pool.

Option(text): Block size (in bytes)

Option Name: core.memory.thread.block.size

Default value: 512

Description:

Specifies the thread stack block size (in bytes).

Option(text): Maximum size of thread stack (in blocks)

Option Name: core.memory.thread.max.size

Default value: 4

Description:

Specifies the maximum number of blocks a thread can use. If a thread requires more blocks a StackOverflow error will occur.

Category: Simulator

../_images/img31.png

Group: Options

Description:

This group specifies options for MicroEJ Simulator.

Option(checkbox): Use target characteristics

Option Name: s3.board.compliant

Default value: false

Description:

When selected, this option forces the MicroEJ Simulator to use the MicroEJ Platform exact characteristics. It sets the MicroEJ Simulator scheduling policy according to the MicroEJ Platform one. It forces resources to be explicitly specified. It enables log trace and gives information about the RAM memory size the MicroEJ Platform uses.

Option(text): Slowing factor (0 means disabled)

Option Name: s3.slow

Default value: 0

Description:

Format: Positive integer

This option allows the MicroEJ Simulator to be slowed down in order to match the MicroEJ Platform execution speed. The greater the slowing factor, the slower the MicroEJ Simulator runs.

Group: HIL Connection

Description:

This group enables the control of HIL (Hardware In the Loop) connection parameters (connection between MicroEJ Simulator and the Mocks).

Option(checkbox): Specify a port

Option Name: s3.hil.use.port

Default value: false

Description:

When selected allows the use of a specific HIL connection port, otherwise a random free port is used.

Option(text): Port

Option Name: s3.hil.port

Default value: 8001

Description:

Format: Positive integer

Values: [1024-65535]

It specifies the port used by the MicroEJ Simulator to accept HIL connections.

Option(text): Timeout (s)

Option Name: s3.hil.timeout

Default value: 10

Description:

Format: Positive integer

It specifies the time the MicroEJ Simulator should wait before failing when it invokes native methods.

Option(text): Maximum frame size (bytes)

Option Name: com.microej.simulator.hil.frame.size

Default value: 262144

Description:

Maximum frame size in bytes. Must be increased to transfer large arrays to native side.

Group: Shielded Plug server configuration

Description:

This group allows configuration of the Shielded Plug database.

Option(text): Server socket port

Option Name: sp.server.port

Default value: 10082

Description:

Set the Shielded Plug server socket port.

Group: Advanced Simulation Options

When running large applications, the Simulator can abruptly reach a memory limit with the following trace:

[...] An error message [...]
"Internal limits reached. Please contact [email protected]"
See error log file: /tmp/microej/s3/s3_1616489929186.log

Depending on the error message, one of the following options must be set to increase the size of the memory area which is full.

Option: Objects Heap Size

Error Message: java.lang.OutOfMemoryError exception thrown

Option Name: S3.JavaMemory.HeapSize

Default value: 4096 (kilobytes)

Description:

This memory area contains any kind of objects (regular, immortal and immutable objects). If you get a java.lang.OutOfMemoryError exception but your Java Heap is not full, most likely you should augment this option. It must be greater than the sum of Java Heap and Immortal Heap.

Option: System Chars Size

Error Message: Failed to allocate internString.

Option Name: S3.JavaMemory.SystemCharsSize

Default value: 1024 (kilobytes)

Description:

This memory area contains system interned strings. System interned strings are likely allocated by the debugger. If you get a Failed to allocate internString. message while debugging an Application, most likely you should augment this option.

Option: Application Chars Size

Error Message: Failed to allocate internString.

Option Name: S3.JavaMemory.ApplicationCharsSize

Default value: 4096 (kilobytes)

Description:

This memory area contains Application interned strings (String literals). If you get a Failed to allocate internString. message while the Simulator is starting the Application, most likely you should augment this option.

Option: Methods Size

Error Message: Failed to allocate method's code.

Option Name: S3.JavaMemory.MethodsSize

Default value: 10000 (kilobytes)

Description:

This memory area contains loaded methods code.

Option: Thread Stack Size

Error Message: The simulator has encountered a stack overflow error while analyzing method [...]

Option Name: S3.JavaMemory.ThreadStackSize

Default value: 300 (kilobytes)

Description:

This memory area contains all Application threads stacks.

Option: Icetea Heap End

Error Message: S3 internal heap is full.

Option Name: IceteaRuntimeSupport.S3.HeapEnd

Default value: 64000000 (bytes)

Description:

This is the overall Simulator memory limit. It includes fixed sizes internal structures and all memory areas. The value must be greater than the size of the memory areas that can be parameterized above.

Option: Symbol Table Size

Error Message: Symbols table area is full.

Option Name: S3.SymbolTable.MaxNbState

Default value: 500000

Description:

This is the number of symbols that can be handled by the internal symbol table (any kind of names: class names, method names, …).

Category: Code Coverage

../_images/img41.png

Group: Code Coverage

Description:

This group is used to set parameters of the code coverage analysis tool.

Option(checkbox): Activate code coverage analysis

Option Name: s3.cc.activated

Default value: false

Description:

When selected it enables the code coverage analysis by the MicroEJ Simulator. Resulting files are output in the cc directory inside the output directory. You can process these files to an HTML report afterward with the built-in Code Coverage Analyzer .

Option(text): Saving coverage information period (in sec.)

Option Name: s3.cc.thread.period

Default value: 15

Description:

It specifies the period between the generation of .cc files.

Category: Debug

../_images/img5.png

Group: Remote Debug

Option(text): Debug port

Option Name: debug.port

Default value: 12000

Description:

Configures the JDWP debug port.

Format: Positive integer

Values: [1024-65535]

Category: Heap Dumper

../_images/img6.png

Group: Heap Inspection

Description:

This group is used to specify heap inspection properties.

Option(checkbox): Activate heap dumper

Option Name: s3.inspect.heap

Default value: false

Description:

When selected, this option enables a dump of the heap each time the System.gc() method is called by the MicroEJ Application.

Category: Logs

../_images/img7.png

Group: Logs

Description:

This group defines parameters for MicroEJ Simulator log activity. Note that logs can only be generated if the Simulator > Use target characteristics option is selected.

Some logs are sent when the Simulator executes some specific action (such as start thread, start GC, etc), other logs are sent periodically (according to defined log level and the log periodicity).

Option(checkbox): system

Option Name: console.logs.level.low

Default value: false

Description:

When selected, System logs are sent when the Simulator executes the following actions:

start and terminate a thread

start and terminate a GC

exit

Option(checkbox): thread

Option Name: console.logs.level.thread

Default value: false

Description:

When selected, thread information is sent periodically. It gives information about alive threads (status, memory allocation, stack size).

Option(checkbox): monitoring

Option Name: console.logs.level.monitoring

Default value: false

Description:

When selected, thread monitoring logs are sent periodically. It gives information about time execution of threads.

Option(checkbox): memory

Option Name: console.logs.level.memory

Default value: false

Description:

When selected, memory allocation logs are sent periodically. This level allows to supervise memory allocation.

Option(checkbox): schedule

Option Name: console.logs.level.schedule

Default value: false

Description:

When selected, a log is sent when the Simulator schedules a thread.

Option(checkbox): monitors

Option Name: console.logs.level.monitors

Default value: false

Description:

When selected, monitors information is sent periodically. This level permits tracing of all thread state by tracing monitor operations.

Option(text): period (in sec.)

Option Name: console.logs.period

Default value: 2

Description:

Format: Positive integer

Values: [0-60]

Defines the periodicity of periodical logs.

Category: Mock

../_images/img8.png

Description:

Specify Hardware In the Loop Mock client options

Group: Debug

Option(checkbox): Enable Mock debug

Option Name: com.microej.simulator.hil.debug.enabled

Default value: false

Option(text): Port

Option Name: com.microej.simulator.hil.debug.port

Default value: 8002

Category: Kernel

../_images/img9.png

Group: Kernel UID

Option(checkbox): Enable

Option Name: com.microej.simulator.kf.kernel.uid.enabled

Default value: false

Option(text): UID

Option Name: com.microej.simulator.kf.kernel.uid

Default value: (empty)

Category: Libraries

../_images/img10.png

Category: EDC

../_images/img111.png

Group: Java System.out

Option(checkbox): Use a custom Java output stream

Option Name: core.outputstream.disable.uart

Default value: false

Description:

Select this option to specify another Java System.out print stream.

If selected, the default Java output stream is not used by the Java application. The Core Engine will not use the default Java output stream at startup.

Option(text): Class

Option Name: core.outputstream.class

Default value: (empty)

Description:

Format: Java class like packageA.packageB.className

Defines the Java class used to manage System.out.

At startup the Core Engine will try to load this class using the Class.forName() method. If the given class is not available, it will use the default Java output stream as usual. The specified class must be available in the application classpath.

Group: Runtime options

Description:

Specifies the additional classes to embed at runtime.

Option(checkbox): Embed UTF-8 encoding

Option Name: cldc.encoding.utf8.included

Default value: true

Description:

Embed UTF-8 encoding.

Option(checkbox): Enable SecurityManager checks

Option Name: com.microej.library.edc.securitymanager.enabled

Default value: false

Description:

Enable the security manager Permission checks.

Category: Shielded Plug

../_images/img12.png

Group: Shielded Plug configuration

Description:

Choose the database XML definition.

Option(browse): Database definition

Option Name: sp.database.definition

Default value: (empty)

Description:

Choose the database XML definition.

Category: External Resources Loader

../_images/img13.png

Group: External Resources Loader

Description:

This group allows to specify the external resources input folder. The content of this folder will be copied in an application output folder and used by SOAR and the Simulator. If empty, the default location will be [output folder]/externalResources, where [output folder] is the location defined in Execution tab.

Option(browse):

Option Name: ej.externalResources.input.dir

Default value: (empty)

Description:

Browse to specify the external resources folder..

Category: Device

../_images/img14.png

Category: Core Engine

../_images/img15.png

Group: Memory

Option(text): Maximum number of monitors per thread

Option Name: core.memory.thread.max.nb.monitors

Default value: 8

Description:

Specifies the maximum number of monitors a thread can own at the same time.

Option(text): Maximum number of frames dumpers on OutOfMemoryError

Option Name: core.memory.oome.nb.frames

Default value: 5

Description:

Specifies the maximum number of stack frames that can be dumped to the standard output when Core Engine throws an OutOfMemoryError.

Option(checkbox): Enable Java heap usage monitoring

Option Name: com.microej.runtime.debug.heap.monitoring.enabled

Default value: false

Option(text): Java heap initial size

Option Name: com.microej.runtime.debug.heap.monitoring.init.size

Default value: 0

Description:

Specify the initial size (in bytes) of the Java Heap.

Group: SOAR

Option(checkbox): Enable Bytecode Verifier

Option Name: soar.bytecode.verifier

Default value: Standalone Application: false, Sandboxed Application: true

Description:

Enables Binary Code Verifier during application build.

In the context of building a Standalone Application, the bytecode verifier is, by default, disabled to prioritize performance. In this case, the code is considered trusted. Conversely, when building a Sandboxed Application, the bytecode verifier is automatically enabled by default. This is particularly important when dealing with untrusted third-party code.

Group: Garbage Collector

Option(text): GC mark stack size

Option Name: com.microej.runtime.core.gc.markstack.levels.max

Default value: 32

Description:

Indicates the quantity of items in the Garbage Collector’s mark stack. The mark stack is used by the Garbage Collector for identifying live objects within the heap through a depth-first search approach. Once the mark stack reaches its capacity, the Garbage Collector proceeds to inspect heap memory, which may slow down garbage collection performance.

You can receive a notification when the mark stack limit is reached by implementing the following hook:

void LLMJVM_on_GC_MarkStackOverflow_reached(void) {
   // When entering here, the GC mark stack is undersized, which may affect GC performance.
   // It is recommended to either increase the GC mark stack size or reduce the object graph depth.
}

Category: Kernel

../_images/img16.png
Group: Threads
Option(text): Maximum number of threads per Feature

Option Name: core.memory.feature.max.threads

Default value: 5

Description:

Specifies the maximum number of threads a Feature is allowed to use at the same time.

Option(text): Feature stop timeout

Option Name: com.microej.runtime.kf.waitstop.delay

Default value: 2000

Description:

Specifies the maximum time allowed for the FeatureEntryPoint.stop() method to return (value in milliseconds).

Group: Features Installation
Option(text): Maximum number of installed Features

Option Name: com.microej.runtime.kernel.dynamicfeatures.max

Default value: 16

Description:

Specifies the maximum number of Features that can be installed to this Kernel (see Kernel.install() method).

Option(text): Code chunk size

Option Name: com.microej.soar.kernel.featurecodechunk.size

Default value: 65536

Description:

Specifies the size in bytes of the code chunk in RAM. See Code Chunk Size section for more details.

Option(text): InputStream transfer buffer size

Option Name: com.microej.runtime.kf.link.transferbuffer.size

Default value: 512

Description:

Specifies the size in bytes of the temporary byte array for reading in the Feature InputStream. See InputStream Transfer Buffer Size section for more details.

Option(text): Maximum number of relocations applied simultaneously

Option Name: com.microej.runtime.kf.link.chunk.relocations.count

Default value: 128

Group: Feature Portability Control
Option(checkbox): Enable Feature Portability Control

Option Name: com.microej.soar.kernel.featureportabilitycontrol.enabled

Default value: false

Option(browse): Kernel Metadata File

Option Name: com.microej.soar.kernel.featureportabilitycontrol.metadata.path

Default value: (empty)

Description:

Specifies the path to the Kernel metadata file for Feature Portability Control.

Category: Watchdog

../_images/img17.png
Option(checkbox): Enable watchdog support

Option Name: enable.watchdog.support

Default value: true

Group: Watchdog
Option(text):

Option Name: maximum.active.watchdogs

Default value: 4

Description:

Specifies the maximum number of active watchdogs at the same time.

Category: Deploy

../_images/img18.png

Description:

Configures the output locations where store the Application, the Architecture libraries and Abstraction Layer header files.

See Board Support Package (BSP) connection chapter for more details.

Group: Configuration

Option(checkbox): Deploy the Application (microejapp.o) at a location known by the 3rd-party BSP project.

Option Name: deploy.bsp.microejapp

Default value: true

Description:

Deploy the Application (microejapp.o) at a location known by the 3rd-party BSP project.

Option(browse):

Option Name: deploy.dir.microejapp

Default value: (empty)

Description:

Choose an output folder where to deploy the Application. An empty value means no deployment (file is available in the Application output folder).

Option(checkbox): Deploy the Architecture library (microejruntime.a) at a location known by the 3rd-party BSP project.

Option Name: deploy.bsp.microejlib

Default value: true

Description:

Deploy the Architecture library (microejruntime.a) at a location known by the 3rd-party BSP project.

Option(browse):

Option Name: deploy.dir.microejlib

Default value: (empty)

Description:

Choose an output folder where to deploy the Architecture library. An empty value means no deployment (file is available in the Application output folder).

Option(checkbox): Deploy the Abstraction Layer header files (*.h) at a location known by the 3rd-party BSP project.

Option Name: deploy.bsp.microejinc

Default value: true

Description:

Deploy the Abstraction Layer header files (*.h) at a location known by the 3rd-party BSP project.

Option(browse):

Option Name: deploy.dir.microejinc

Default value: (empty)

Description:

Choose an output folder where to deploy the Architecture library. An empty value means no deployment (file is available in the Application output folder).

Option(checkbox): Execute the MicroEJ build script (build.bat) at a location known by the 3rd-party BSP project.

Option Name: deploy.bsp.microejscript

Default value: false

Description:

Execute the MicroEJ build script (build.bat) at a location known by the 3rd-party BSP project.

Option(browse):

Option Name: deploy.dir.microejscript

Default value: (empty)

Description:

Choose an output folder where is located the MicroEJ build script (build.bat) to execute. An empty value means no execution.

Option(browse):

Option Name: deploy.bsp.root.dir

Default value: (empty)

Description:

Choose an output folder where is located the 3rd-party BSP project. An empty value means not set (3rd-party BSP project location may have been configured by the VEE Port).

Category: Feature

../_images/img19.png

Description:

Specify Feature options

Group: Build

Option(text): Output Name

Option Name: feature.output.basename

Default value: application

Option(browse): Kernel

Option Name: kernel.filename

Default value: (empty)