Kernel API Generator

Principle

The Kernel API Generator is a tool that helps to generate a kernel.api file based on a Java classpath. The generated file lists the public and protected types, methods and fields of the selected classes, as well as those of their supertypes.

Use

SDK 6 1.8.0 and higherSDK 6 1.7.0 and below

To generate the kernel.api file, execute the generateKernelApi task as follows:

./gradlew generateKernelApi

This task is available in Application and Add-On Library projects. It compiles the project sources itself, so there is no need to execute the build task first.

The kernel.api file is generated in the build/kernelApi directory of the project, which is created if it does not exist.

By default, all the classes compiled by the project are used to generate the Kernel API. To select a subset of them, configure the options described in Options.

The generateKernelApi task is not executed by the build task and no other task consumes its output, so it must be executed explicitly each time the API exposed by the Kernel changes. The generated file must then be stored at the root of the Application classpath, usually the src/main/resources directory of the Kernel project or of the Runtime Environment project.

Warning

A supertype which is not on the classpath is skipped by the tool, without any error or warning message, so an incomplete classpath produces an incomplete kernel.api file. Execute the task with the --info option to print the classpath used by the tool:

./gradlew generateKernelApi --info

When the generation fails, the task deletes the kernel.api file, so the build directory never keeps an outdated file.

Options

SDK 6 1.8.0 and higherSDK 6 1.7.0 and below

The tool is configured with the properties of the generateKernelApi task, in the build.gradle.kts file of the project:

import com.microej.gradle.tasks.GenerateKernelApiTask

tasks.named<GenerateKernelApiTask>("generateKernelApi") {
    includes.set(listOf("com/mycompany/kernel/**"))
    excludes.set(listOf("**/internal/**"))
}

• includes: Ant-style patterns of the classes to include, relative to the directory of the classes compiled by the project.

  • Default value: **/*.class (which means all the classes compiled by the project).

• excludes: Ant-style patterns of the classes to exclude, relative to the directory of the classes compiled by the project.

  • Default value: empty (which means no excluded classes).

• classpath: Classpath searched by the tool.

  • Default value: the runtime classpath of the project, which contains the classes compiled by the project, its resources and its dependencies.

  • The include and exclude patterns are matched against the directories of this classpath, which contain the classes compiled by the project. The JAR files of this classpath, which contain the dependencies, are searched to resolve the supertypes of the selected classes, but their classes are never selected.

• outputDirectory: Directory of the generated kernel.api file.

  • Default value: build/kernelApi.

The task fails when no class matches the include and exclude patterns, instead of generating an empty file.