Forge
How-to guides

Configure code quality

Configure Spotless, JaCoCo and ProGuard through Forge.

Forge configures three code-quality tools. It applies jacoco and com.diffplug.spotless itself, each gated on a switch that defaults on, so most projects touch neither plugins { } nor these properties for either one. ProGuard is different: it is not a plugin Forge applies, so a project adds it to its own buildscript classpath and opts in explicitly.

Every flag reads as enabled only when its value is the literal true, in any casing; anything else disables it, and the build reports the decision in the configuration log.

Spotless and JaCoCo

Both default on. Forge applies jacoco and com.diffplug.spotless itself, immediately after it reads the project's properties, so neither belongs in your own plugins { } block. Declaring id("com.diffplug.spotless") version "..." there cannot resolve — Spotless is already on the buildscript classpath, at the version Forge pins.

Forge pins a JaCoCo tool version that understands class files through Java 21, the top of the toolchain range the support matrix spans, and wires the report tasks. For Spotless it applies the ktlint formatting and the license header from the project's spotless-header.txt. A missing or blank header file fails the build — see The licence header is required below.

The header step writes above the first line of file content, which in Kotlin is a @file: annotation when the file carries one. @file:JvmName, @file:Suppress and every other @file: target survive spotlessApply, in .kt sources and in .gradle.kts build scripts alike. A project that excluded such a file through targetExclude may drop the exclusion and recover ktlint coverage on it.

What Spotless formats

Forge declares four Spotless formats, each with its own generated spotlessX and spotlessXCheck task.

FormatTaskTargetSteps
javaspotlessJavasrc/**/*.javalicence header, googleJavaFormat().aosp(), import order, unused-import removal
kotlinspotlessKotlinsrc/**/*.ktlicence header, ktlint()
kotlinGradlespotlessKotlinGradle*.gradle.ktslicence header, ktlint()
markupspotlessMarkupsrc/main/assembly/**/*.{xml,umd,html,htm}licence header

Every format also trims trailing whitespace and ends the file with a newline. A <pre> block in an assembly HTML page loses its trailing spaces for that reason.

The markup format covers everything in the assembly that carries an SGML-family comment, because the placement rule is the same for all of it: the licence block goes below any prolog and above the first real element. An XML file keeps its declaration and its doctype on top; an HTML page keeps <!DOCTYPE html> on top, since anything above a doctype drops a browser into quirks mode. A second spotlessApply replaces the block a previous run wrote rather than stacking a second one.

HTML pages a resource ships as help therefore carry the same licence the rest of the distribution carries, without you listing them anywhere.

A build script or a CI job that invokes a per-format task by name calls spotlessMarkup or spotlessMarkupCheck for this format. spotlessApply and spotlessCheck cover every format and need no per-format name.

Disable either tool independently:

com.mbseconsulting.forge.configure.jacoco=false
com.mbseconsulting.forge.configure.spotless=false

JaCoCo has one level of override: turn it off and configure the jacoco plugin yourself, the way any Gradle project would. Spotless has three, described next.

Dokka is documented separately

Forge also applies Dokka and packages the rendered API reference, but that generates documentation rather than gating quality, so it has its own page: Generate an API reference.

Turning Spotless off, or taking it over

Forge applies Spotless and configures Java, Kotlin, Gradle Kotlin DSL and markup formats. Three levels of override are available, from lightest to heaviest.

Stop the formatting gate without losing spotlessApply:

spotless { isEnforceCheck = false }

Change what a format targets, or what it ignores. These are plain settings, so the last write wins:

spotless { kotlin { targetExclude("src/main/kotlin/generated/**") } }

Re-author a format completely. clearSteps() first, always:

spotless {
    kotlin {
        clearSteps()
        licenseHeader("/* your header */")
        ktlint("1.5.0")
        endWithNewline()
    }
}

Adding a step Forge already added is a build failure, not an override — Multiple steps with name 'ktlint' for spotless format 'kotlin'. Spotless rejects a duplicate step name rather than replacing the step, so clearSteps() is the only way to change one Forge set.

A format you clear loses the licence header Forge builds from your resource.provider* and legal.* keys, while generateResourceDescriptor and generatePluginDescriptor keep stamping that header into the XML they generate. Your sources and your descriptors then carry different headers. Forge cannot detect this — Spotless exposes no way to read a format's steps — so re-declare the header yourself if you clear a format.

The licence header is required

Forge builds the header from your resource.provider* and legal.* keys and a spotless-header.txt in your project root. Whenever Spotless is configured — on by default, or through your own configure.spotless=true — a missing or blank spotless-header.txt fails the build, naming the file it expected. The same failure covers the seven resource.* and legal.* keys the header substitutes: one left blank fails the build the same way.

A project that does not want the header sets com.mbseconsulting.forge.configure.spotless=false.

Turning Spotless off entirely

Set com.mbseconsulting.forge.configure.spotless=false. Forge then applies nothing and configures nothing. Spotless stays on your buildscript classpath, because Forge depends on it, so declare it without a version if you want to apply it yourself:

plugins {
    id("com.mbseconsulting.forge") version "9.0.0"
    id("com.diffplug.spotless")   // no version — a versioned request cannot resolve
}

Your project still declares its repositories

Forge adds the CATIA Magic release and snapshot repositories, and nothing else. Every tool Forge applies resolves its own artifacts from your repositories when its tasks run — Spotless downloads ktlint and google-java-format, and Dokka its rendering engine — so your build.gradle.kts keeps:

repositories {
    mavenCentral()
}

Without it spotlessKotlin fails with Could not resolve all files for configuration ':detachedConfigurationN'.

ProGuard

ProGuard is not a plugin you apply, so put it on the buildscript classpath:

buildscript {
    repositories {
        gradlePluginPortal()
    }
    dependencies {
        classpath("com.guardsquare:proguard-gradle:7.9.1")
    }
}

Then enable the wiring:

com.mbseconsulting.forge.configure.proguard=true

Forge registers an obfuscate task and rewires assemblePlugin to consume the obfuscated jar rather than the original, so the archive ships obfuscated code without any further configuration.

Disable it with com.mbseconsulting.forge.configure.proguard=false, which is also the behaviour when the key is absent.

Coverage reports

With JaCoCo enabled, both test tasks produce an execution file:

./gradlew jacocoTestReport
./gradlew jacocoTestCoverageVerification

integrationTest runs as a JavaExec rather than a Test task, so the JaCoCo plugin does not attach to it on its own. Forge attaches the extension explicitly, which is what instruments the forked JVM. See Write tests.

Both report tasks depend on every Test and IntegrationTest task, so they run the tests before reading the execution data rather than reading whatever a previous run left behind. Two consequences follow: the coverage gate that jacocoTestCoverageVerification enforces cannot pass vacuously against empty execution data; and jacocoTestReport transitively launches integrationTest, which forks a JVM against a real CATIA Magic install and consumes a licence. That second consequence reaches only a project carrying a @Tag("IntegrationTest") test, because integrationTest skips when none exists.

A task excluded with -x runs in no part of the build, so its execution file on disk comes from an earlier run. Both tasks leave that file out. jacocoTestCoverageVerification also skips whenever a test task is excluded, and logs which one: ./gradlew check -x integrationTest reports coverage from unit tests alone and applies no gate.

check depends on both tasks, so ./gradlew build produces the report and applies the 80% gate. A project below that floor fails its build. Raise coverage, or demote the gate:

tasks.jacocoTestCoverageVerification {
    violationRules {
        isFailOnViolation = false
    }
}

Generated profile bindings do not count toward that gate. generateProfileBindings stamps every type it emits with @Generated, and JaCoCo drops each class carrying an annotation whose simple name contains Generated. The filter runs inside the analyzer, so the generated layer leaves the report and the gate's denominator together, and the number the gate reads measures the code the project wrote. The annotation comes from Anvil, so a project must resolve a version that declares it. See Generate profile bindings.

The edges exist only while com.mbseconsulting.forge.configure.jacoco=true. Setting the key to false leaves the check graph as the jacoco plugin built it.

On this page