Forge
Reference

Tasks

Every task Forge registers, its group, and its lifecycle wiring.

Forge registers its tasks under six groups, so ./gradlew tasks lists them together.

Configuration cache

Forge's tasks run under Gradle's configuration cache, enabled per build with --configuration-cache or for a repository with org.gradle.configuration-cache=true in gradle.properties. A build reuses the stored entry unless something Forge reads while it configures the build has changed. Forge reads these while it configures:

What Forge readsA build configures again after
The source folders src/main/java, src/main/kotlin and src/test/kotlin, and the profiles under src/main/assembly/profilesadding, removing or editing a file in one of them
The jars under the CATIA Magic installation's lib/ and plugins/ foldersinstallCatiaMagicDependencies changes the installed plugins
dev-env/user.propertiesinstallJdk, installJre or installCatiaMagic records a new location; a reinstall to the same location leaves the file unchanged
The publication index under build/the first build after a clean build/ directory writes it, so the second build configures again

Each case costs one configuration, and the next build without such a change reuses the entry.

Forge - Environment

These tasks prepare a development environment: they fetch the tool, a JDK and a JRE, and the resources a project depends on.

TaskPurpose
listCatiaMagicVersionsList the CATIA Magic archives on the assets repository, with preset and AI-docs availability
downloadCatiaMagicDownload one CATIA Magic archive, its user preset, and its AI-docs digest. Usage: -Pfile=<archive>
installCatiaMagicExtract the archive into dev-env/. Usage: -Pfile=<archive>
installAiDocsExtract the AI-docs digest to dev-env/ai-docs/
downloadJdkDownload the JDK matching resource.mdVersionMin
downloadJreDownload the JRE matching resource.mdVersionMin
installJdkExtract the JDK and record its location
installJreExtract the JRE and record its location
installCatiaMagicDependenciesResolve the catiaMagic configuration and install every resource and plugin it names, transitively

installCatiaMagic is finalized by installAiDocs rather than depending on it. A missing digest is the normal case and must never hold up a tool install; see The AI-docs digest.

Forge - Catalog

Catalog tasks scan installations and repositories and write the JSON indexes that the publication guard later reads.

TaskPurpose
createManifestScan an installation and write manifest.json describing what it contains
createExternalZipIndexParse the archives named by externalZips and write external-index.json
createRegistryCombine the repositories, external-index.json and the project's own publication-index.json into registry.json

createRegistry reports every artifact it refuses, naming the artifact and the reason, and fails when a repository search returns a non-2xx status or a remote repository URL matches neither Nexus 3 nor Artifactory. A partial registry.json is indistinguishable from a complete one, and Forge's redeploy guard reads that file at publication, so a silently dropped artifact resurfaces later as an unresolvable dependency or a 400 on publish. An ordinary Maven artifact — a POM with no artifactDetection property — is not a refusal and is not reported.

Forge - Verification

TaskPurpose
validateGradlePropertiesCheck every property against its rule
validatePluginClassCheck that the compiled plugin class extends com.nomagic.magicdraw.plugins.Plugin, is concrete and has a public no-argument constructor
verifyJdkCheck that the JDK matching resource.mdVersionMin is installed
verifyJreCheck that the JRE matching resource.mdVersionMin is installed
generateIntegrationSupportGenerate the integration-test runner into the test source set
testRun tests tagged @Tag("UnitTest")
installResourceForTestInstall the assembled resource into the CATIA Magic installation so a test model resolves the project's own profiles
uninstallResourceForTestRemove that installed resource once integrationTest finishes, whether it passed or failed
integrationTestRun tests tagged @Tag("IntegrationTest") in a forked JVM
generateReportWrite build/reports/forge/report.html and report.json from whatever unit, integration and coverage output the build produced, and copy both into build/distributions/ under the resource archive name

test and integrationTest exist only when configure.testing=true. integrationTest, installResourceForTest and uninstallResourceForTest are registered additionally only when catia.magic.installation.directory is set, because the tests need a real installation and a licence. integrationTest depends on installResourceForTest and is finalized by uninstallResourceForTest, so the resource is installed before the fork and removed afterwards even when the tests fail. All three skip together when no source declares @Tag("IntegrationTest"). integrationTest takes the resource archive as an input beside the test classpath, because the fork loads the project's profiles and model libraries from the installed copy. Editing a shipped .mdzip, a static file or the plugin therefore re-runs the suite. Both test and integrationTest pass the absolute path of src/main/assembly/ to their JVM as the system property forge.integration.assemblyDir. test takes that directory's content as an input, keyed by relative path, so editing a file under it re-runs the unit tests and moving the checkout does not. See Write tests for the tags and Integration testing for the fork.

generateReport registers unconditionally, so a project with configure.testing=false still gets a report, one stating that no test task ran. It never fails the build: a missing input is a rendering state rather than an error, and the test tasks and the coverage gate keep their existing authority over the build's outcome.

It writes four files. build/reports/forge/report.html and report.json are the canonical pair, in the tree Gradle prints and CI reporters scan. The other two are copies in build/distributions/, named <resource-archive-name>-report.html and <resource-archive-name>-report.json — acme-profile-1.4.0-2024x.zip ships beside acme-profile-1.4.0-2024x-report.html and acme-profile-1.4.0-2024x-report.json — so the release set carries the report describing the build that produced its archives. The copies are optional output: the names derive from resource.name and resource.humanVersion, and without them the canonical pair is still written and no copy is delivered. Publication reads build/publication/publication-index.json rather than scanning the folder, so neither copy reaches a Maven repository.

Its trigger is not simply check.finalizedBy(generateReport). Gradle drops a task's finalizers whenever that task itself is skipped because one of its own dependencies failed, and check is skipped exactly when test, integrationTest or a JaCoCo report task fails — the case the report exists to explain. A check-only edge would therefore produce no report on the one build a reader most wants to see. Forge instead finalizes check and every Test, IntegrationTest and JacocoReport task, so whichever task actually runs and fails still carries its own finalizer edge regardless of what happens to check. See The unified test and coverage report for the reasoning and Properties for report.source and report.git.

Forge - Assemble

Assembly tasks turn sources and static files into the distribution archives.

TaskPurpose
assembleStaticFilesCopy static assets from the assembly directory, excluding .gitkeep, .mdzip, MagicDraw working artifacts, and the plugins folder
patchMdzipsCopy each shipped .mdzip and set its project properties: standardProfile outside samples/ and templates/, internalVersion from resource.humanVersion, and the Author and Title lines of the root model's documentation, which it creates when the model has none. The source file stays untouched
stageMerge original files and patched .mdzip files into the staging directory
assemblePluginCopy the plugin jar and its runtime dependencies into place
generateResourceDescriptorWrite the resource descriptor XML
generatePluginDescriptorWrite plugin.xml
generateLegalFilesValidate the legal properties and write LICENSE, NOTICE and ARTIFACT-INFO
zipResourcePackage the resource archive
zipPluginPackage the plugin archive
zipSourcesPackage the project sources declared in the forge { sources { } } block into <resource-archive-name>-sources.zip
zipApiDocsPackage the API reference Dokka renders from the project's KDoc into <resource-archive-name>-apidocs.zip
createPublicationIndexMerge the resource and plugin metadata into publication-index.json
obfuscateObfuscate the plugin jar with ProGuard
generateProfileBindingsGenerate Kotlin bindings from the .mdzip profiles under src/main/assembly/profiles/

zipSources registers unconditionally and runs only when the sources block names at least one include. An unconfigured project sees SKIPPED rather than an unknown-task error. assemble depends on it; it packages sources rather than build output, so it may run before the other archives. Its output reaches no Maven repository, because publication reads publication-index.json and this task writes no entry there. See Package the project sources.

zipApiDocs also registers unconditionally, and assemble depends on it. Its onlyIf reads its own apiDocs property rather than the plugin manager, because an onlyIf spec runs at execution time, where reading project breaks the configuration cache; Forge sets apiDocs's convention only inside pluginManager.withPlugin("org.jetbrains.dokka"), so the property is present exactly when Dokka is applied, which Forge does for a project that carries Kotlin sources and leaves configure.dokka on. A model-only resource sees SKIPPED rather than an unknown-task error. The convention is dokkaGeneratePublicationHtml's own output directory, taken as a provider, so Gradle orders the render before the packaging without an explicit dependsOn. Its output reaches no Maven repository, for the same reason zipSources's does not. See Generate an API reference.

ZipSources extends Zip, so the inherited include() and exclude() methods stay callable directly on the task. tasks.named<ZipSources>("zipSources") { include("x") } therefore reaches PatternFilterable's own copy-spec filter, not includePatterns, and the two carry different semantics. Declare patterns through the forge { sources { } } block instead — the path this task actually reads.

The inherited from() carries a sharper edge, because it adds files to the copy spec rather than filtering what the block named. A from() call on the task therefore puts a path into the archive that no include declares. Both guards still read the resolved tree, so neither is bypassed, but the sources block a reviewer reads no longer describes everything that ships.

generateLegalFiles writes its three files to its own directory under build/tmp/. stage copies them into legal/mbseconsulting/<artifactId>/ inside the resource zip, and the jar task copies them into META-INF/. Both read the output directory through a provider, which carries the task dependency, so neither declares an explicit edge to generateLegalFiles. The task validates its own inputs and throws rather than leaving the check to validateGradleProperties, so ./gradlew assemble is gated on every invocation path, including one that never reaches check.

obfuscate differs from the rest: it appears only when configure.proguard=true and the project puts ProGuard on the buildscript classpath. Registering it also rewires assemblePlugin to consume the obfuscated jar. See Configure code quality.

stage, generateResourceDescriptor and zipResource always have source, so none of them reports NO-SOURCE. stage is a Sync task, and Gradle marks AbstractCopyTask.getSource() @SkipWhenEmpty. The legal files are always present, because generateLegalFiles throws before leaving its output directory empty. A project with no other content still stages, describes and zips its legal files.

generateProfileBindings runs by default and in the Gradle daemon's own JVM, because the generator is compiled into Forge; the plugin version therefore selects the generator, and nothing resolves a Maven coordinate. A project that ships no .mdzip is NO-SOURCE, and one that sets com.mbseconsulting.forge.configure.codegen=false is SKIPPED with its output directory left untouched.

The task takes the jars under the CATIA Magic installation's lib/ and plugins/ as an input, from which it scans the UML metaclass table used to type the bindings. It reads entry names and loads no class, so a machine with no installation still generates, emitting Element for every metaclass it could not resolve. See Generate profile bindings.

The task stamps the license header from spotless-header.txt on every .kt it emits, inside its own action. Spotless targets src/ alone and never sees build/generated/forge/profiles/.

Forge - Build

Each group also carries the lifecycle task that enters it: assemble, check and build.

Forge - Publishing

TaskPurpose
publishAssetUpload a file or directory to a raw repository. Usage: -Psource=<path> [-Pdestination=<path>]
publishSnapshotsPublish every snapshot publication
publishReleasesPublish every release publication
publishAllPublish snapshots or releases, according to the version

Forge creates one Maven publication per resource and per plugin found in the on-disk indexes. Those indexes must exist before the publication tasks resolve, which makes a first run of publishAll a two-pass operation. See Publish a resource.

Lifecycle wiring

Forge attaches its tasks to the standard Gradle lifecycle, so the usual commands pull in the right work.

Lifecycle taskDepends on
checkverifyJdk, verifyJre, validateGradleProperties
checkvalidatePluginClass
checkintegrationTest
checkjacocoTestReport, jacocoTestCoverageVerification
generatePluginDescriptorvalidatePluginClass
assemblecreatePublicationIndex
assemblezipSources
assemblezipApiDocs
compileKotlingenerateProfileBindings
jacocoTestReporttasks.withType(Test), tasks.withType(IntegrationTest)
jacocoTestCoverageVerificationtasks.withType(Test), tasks.withType(IntegrationTest)

generatePluginDescriptor depends on validatePluginClass because plugin.xml names the plugin class, and publication runs assemble without check. A class CATIA Magic cannot load therefore fails assemble rather than reaching an archive. validatePluginClass reads the compiled class, so it runs after compilation and follows the superclass chain through the compile classpath.

The compileKotlin edge carries no explicit dependsOn. generateProfileBindings registers its output directory on the main source set as a Provider<Directory>, and that provider carries the task dependency with it.

Each check edge appears only when its target exists. integrationTest is registered when configure.testing=true and catia.magic.installation.directory is set, so a machine without an installation gets no edge and no unresolvable dependency. The two JaCoCo edges require both the jacoco plugin and configure.jacoco=true: a project that applies the plugin and sets the property to false has asked Forge to leave its JaCoCo graph alone, and keeps its own check.

integrationTest skips when no test source declares @Tag("IntegrationTest"), so a project that declares an installation but has written no integration test builds without forking a JVM or taking a licence. See Write tests.

A full build therefore runs:

./gradlew build

jacocoTestCoverageVerification enforces a minimum of 80% coverage, and check runs it, so a project below that floor fails build. Raise coverage, or demote the gate to a report in the consuming build.gradle.kts:

tasks.jacocoTestCoverageVerification {
    violationRules {
        isFailOnViolation = false
    }
}

violationRules.rules is an unmodifiable list, so the rule cannot be removed. A consumer that wants a different floor sets isFailOnViolation = false and declares its own gate.

Task graph

The diagrams below carry three kinds of edge, and two of the three declare no dependsOn.

EdgeMeans
A --> BExplicit dependsOn. A requires B, so B runs first.
A -.-> BA reads B's output through a Provider, so Gradle infers the dependency.
A -. label .-> BOrdering alone, through finalizedBy or mustRunAfter. A runs first and B after, and neither pulls the other into the graph.

A thick outline marks a Gradle lifecycle task. A dashed outline marks a task that exists only under the property or the plugin its group section above names. The diagrams set no colours, so they take the palette of whichever theme you read GitHub in.

Assemble

Three explicit edges start the pipeline: assemble depends on createPublicationIndex, on zipSources and on zipApiDocs. Every edge below them is provider-carried. stage is the junction, and the three tasks that describe or zip the result all read its directory.

Registering obfuscate re-points assemblePlugin's jar property at the obfuscated jar, so that edge replaces assemblePlugin → jar rather than adding to it.

Check

Four verification edges are unconditional. The rest attach only when their target exists, which keeps a machine without a CATIA Magic installation from acquiring an unresolvable check dependency.

generateReport hangs off four finalizedBy edges rather than one. Gradle drops a task's finalizers when that task is skipped because its own dependency failed, so check alone would produce no report in the one case the report exists to explain — a failing test. Finalizing the producing tasks as well keeps the report arriving on that path.

generateIntegrationSupport reaches testClasses the way the bindings reach compileKotlin: it adds its output to the test source set as a provider. integrationTest declares dependsOn("testClasses") and nothing else.

Environment

Environment tasks are invoked by hand and sit outside the lifecycle. The tool-install chain is the only place several of them connect, and its two ordering edges are the ones most easily misread.

Both labelled edges order tasks without making one depend on the other. installAiDocs is deliberately a dependency of nothing, because a missing digest is the normal case and must never hold up a tool install. It resolves the download location itself rather than reading downloadCatiaMagic's output property, precisely so that no provider edge is created.

installCatiaMagicDependencies reads the installation directory and its manifest.json off disk, then resolves the catiaMagic configuration. Run the install chain first; the graph will not.

Catalog

Catalog tasks describe what already exists on disk or in a repository. One edge joins them, and the file that matters most to createRegistry arrives without one.

createRegistry reads build/publication/publication-index.json through a path provider rather than through createPublicationIndex's output property, so Gradle creates no edge and a stale file is used without warning. Only the createExternalZipIndex input carries a real edge. Run assemble first.

Publishing

Forge generates the publication tasks rather than registering them: it creates one Maven publication per resource and per plugin it finds in the on-disk indexes, then aggregates the resulting publish… tasks. Those indexes must exist before configuration runs, which makes a first publishAll a two-pass operation.

publishAll picks its branch from the version, and only a branch whose publication list is non-empty gets an edge. A SNAPSHOT version therefore yields publishSnapshots alone.

On this page