Forge
How-to guides

Develop and assemble

Lay out static assets and plugin code, and assemble the two output zips.

Add static assets

Drop profiles, model libraries, templates, samples, diagrams and perspectives into src/main/assembly/, each under the folder its kind belongs in:

src/main/assembly/
├── modelLibraries/
├── profiles/
├── samples/
└── templates/

Every file placed there is bundled into the resource archive, and generateResourceDescriptor writes the matching <file> entry into the installation node. You do not list files anywhere by hand.

CATIA Magic resources describes the archive layout these folders produce.

Add plugin code

Write Java under src/main/java or Kotlin under src/main/kotlin. Forge applies the Kotlin plugin automatically when it finds a .kt file in src/main/kotlin or src/test/kotlin, pinning the Kotlin version itself, so a project declares no kotlin("jvm") plugin and no toolchain block. The Java language version follows resource.mdVersionMin, and every Java task runs on the JDK installJdk installs for it.

A project with no sources at all produces no jar: the jar task disables itself when neither source folder holds code, which is what lets a resource ship profiles alone.

The CATIA Magic API needs no dependency declaration. See Declare dependencies.

Run a task on another JDK

A JavaExec or Test task that needs a different JVM names it, and Forge leaves that choice alone. Set executable to a bin/java inside a JDK home, or set javaLauncher:

tasks.register<JavaExec>("runWithJbr") {
    mainClass.set("com.nomagic.magicdraw.Main")
    executable("/path/to/jbr/bin/java")
}

A JavaCompile task names another JDK through options.forkOptions.javaHome, or through options.forkOptions.executable set to a bin/javac. Forge then forks javac from that JDK, and the installed JDK need not exist. Setting the task's javaCompiler instead fails the build, because Forge forks javac from the installed JDK and Gradle rejects the two disagreeing.

tasks.named<JavaCompile>("compileJava") {
    options.forkOptions.javaHome = file("/path/to/jdk-21")
}

A Javadoc task names another JDK through executable, set to a bin/javadoc. Setting its javadocTool instead fails the build for the same reason as javaCompiler.

tasks.named<Javadoc>("javadoc") {
    executable = "/path/to/jdk-21/bin/javadoc"
}

In a project with both Java and Kotlin sources, compileJava and compileKotlin must target the same Java version, or the Kotlin plugin fails the build with Inconsistent JVM Target Compatibility. Point both tasks at the same JDK:

val jdk21 = file("/path/to/jdk-21")
tasks.named<JavaCompile>("compileJava") {
    options.forkOptions.javaHome = jdk21
}
tasks.named<org.jetbrains.kotlin.gradle.tasks.KotlinCompile>("compileKotlin") {
    kotlinJavaToolchain.jdk.use(jdk21, JavaVersion.VERSION_21)
}

Assemble

./gradlew assemble

build/distributions/ then holds up to four archives:

ArchivePurpose
Resource zipWhat you give users, complete and ready to install
Plugin zipFor publication to the repository only
Sources zipThe project sources, written only when the sources block names an include. See Package the project sources
API-docs zipThe API reference Dokka renders, written only when the project carries Kotlin sources. See Generate an API reference

Full build

./gradlew build

check runs the validators and the JDK and JRE verifications alongside the unit tests, then integrationTest and the two JaCoCo tasks where the project configures them. See Tasks for the lifecycle wiring, and Write tests for the test tasks.

generateReport finalizes those tasks, so a full build also leaves the unified test and coverage report pair, report.html and report.json, in build/distributions/, named after the resource archive. assemble alone does not run it. See The unified test and coverage report.

A full build fails below 80% coverage. It also forks a JVM against the CATIA Magic installation and consumes a licence, but only once the project carries a @Tag("IntegrationTest") test — integrationTest skips otherwise. Run ./gradlew assemble check -x integrationTest for a faster loop that still validates the project. That loop skips the 80% gate, because unit coverage alone cannot judge the whole suite, and it leaves out any coverage an earlier integration run recorded.

On this page