Invocation Dynamic Libraries

Contents

• Configuration
• Test Run
• Profiling

Configuration

To create a dynamic library callable from applications written in a non-JVM language instead of a runnable executable, you need to add the plugin dependency to the buildscript configuration of the build.gradle file, e.g.:

buildscript {
    def jetPluginVersion = '1.3.1'
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath "com.excelsiorjet:excelsior-jet-gradle-plugin:$jetPluginVersion"
    }
}

then apply and configure the excelsiorJet plugin as follows:

apply plugin: 'excelsiorJet'
excelsiorJet {
    appType = "dynamic-library"
}

Using such libraries is a bit tricky. Like any other JVM, Excelsior JET executes Java code in a special isolated context to correctly support exception handling, garbage collection, and so on. That is why Java methods cannot be directly invoked from a foreign environment. Instead, you have to use the standard Java SE platform APIs, specifically the Invocation API and Java Native Interface (JNI). See samples/Invocation in your Excelsior JET installation directory for detailed examples.

Test Run

To test an invocation dynamic library, you may set a "test" mainClass in the plugin configuration. The main method of that class should in turn call methods that are subject for usage from a non-JVM language.

Profiling

To enable PGO for an invocation dynamic library, use the same jetProfile task. However, as a separate client application is likely needed to collect a representative execution profile, the plugin would only create a special profiling image at build/jet/appToProfile. That image contains the natively compiled library and any Excelsior JET Runtime files it requires. You would then need to run an application that would load that library and use it extensively.