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 reads | A build configures again after |
|---|---|
The source folders src/main/java, src/main/kotlin and src/test/kotlin, and the profiles under src/main/assembly/profiles | adding, removing or editing a file in one of them |
The jars under the CATIA Magic installation's lib/ and plugins/ folders | installCatiaMagicDependencies changes the installed plugins |
dev-env/user.properties | installJdk, 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.
| Task | Purpose |
|---|---|
listCatiaMagicVersions | List the CATIA Magic archives on the assets repository, with preset and AI-docs availability |
downloadCatiaMagic | Download one CATIA Magic archive, its user preset, and its AI-docs digest. Usage: -Pfile=<archive> |
installCatiaMagic | Extract the archive into dev-env/. Usage: -Pfile=<archive> |
installAiDocs | Extract the AI-docs digest to dev-env/ai-docs/ |
downloadJdk | Download the JDK matching resource.mdVersionMin |
downloadJre | Download the JRE matching resource.mdVersionMin |
installJdk | Extract the JDK and record its location |
installJre | Extract the JRE and record its location |
installCatiaMagicDependencies | Resolve 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.
| Task | Purpose |
|---|---|
createManifest | Scan an installation and write manifest.json describing what it contains |
createExternalZipIndex | Parse the archives named by externalZips and write external-index.json |
createRegistry | Combine 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
| Task | Purpose |
|---|---|
validateGradleProperties | Check every property against its rule |
validatePluginClass | Check that the compiled plugin class extends com.nomagic.magicdraw.plugins.Plugin, is concrete and has a public no-argument constructor |
verifyJdk | Check that the JDK matching resource.mdVersionMin is installed |
verifyJre | Check that the JRE matching resource.mdVersionMin is installed |
generateIntegrationSupport | Generate the integration-test runner into the test source set |
test | Run tests tagged @Tag("UnitTest") |
installResourceForTest | Install the assembled resource into the CATIA Magic installation so a test model resolves the project's own profiles |
uninstallResourceForTest | Remove that installed resource once integrationTest finishes, whether it passed or failed |
integrationTest | Run tests tagged @Tag("IntegrationTest") in a forked JVM |
generateReport | Write 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.
| Task | Purpose |
|---|---|
assembleStaticFiles | Copy static assets from the assembly directory, excluding .gitkeep, .mdzip, MagicDraw working artifacts, and the plugins folder |
patchMdzips | Copy 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 |
stage | Merge original files and patched .mdzip files into the staging directory |
assemblePlugin | Copy the plugin jar and its runtime dependencies into place |
generateResourceDescriptor | Write the resource descriptor XML |
generatePluginDescriptor | Write plugin.xml |
generateLegalFiles | Validate the legal properties and write LICENSE, NOTICE and ARTIFACT-INFO |
zipResource | Package the resource archive |
zipPlugin | Package the plugin archive |
zipSources | Package the project sources declared in the forge { sources { } } block into <resource-archive-name>-sources.zip |
zipApiDocs | Package the API reference Dokka renders from the project's KDoc into <resource-archive-name>-apidocs.zip |
createPublicationIndex | Merge the resource and plugin metadata into publication-index.json |
obfuscate | Obfuscate the plugin jar with ProGuard |
generateProfileBindings | Generate 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
| Task | Purpose |
|---|---|
publishAsset | Upload a file or directory to a raw repository. Usage: -Psource=<path> [-Pdestination=<path>] |
publishSnapshots | Publish every snapshot publication |
publishReleases | Publish every release publication |
publishAll | Publish 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 task | Depends on |
|---|---|
check | verifyJdk, verifyJre, validateGradleProperties |
check | validatePluginClass |
check | integrationTest |
check | jacocoTestReport, jacocoTestCoverageVerification |
generatePluginDescriptor | validatePluginClass |
assemble | createPublicationIndex |
assemble | zipSources |
assemble | zipApiDocs |
compileKotlin | generateProfileBindings |
jacocoTestReport | tasks.withType(Test), tasks.withType(IntegrationTest) |
jacocoTestCoverageVerification | tasks.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 buildjacocoTestCoverageVerification 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.
| Edge | Means |
|---|---|
A --> B | Explicit dependsOn. A requires B, so B runs first. |
A -.-> B | A reads B's output through a Provider, so Gradle infers the dependency. |
A -. label .-> B | Ordering 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.