Forge
Reference

Properties

Every com.mbseconsulting.forge.* property, its default and its validation rule.

Forge reads its settings from Gradle properties. A project declares them in its own gradle.properties; a user declares machine-specific ones such as credentials in ~/.gradle/gradle.properties. Project keys override user-home keys of the same name.

Every user-facing key carries the prefix com.mbseconsulting.forge.. The tables below drop that prefix in the Key column and restore it in the examples. validateGradleProperties enforces the rules in the Rule column.

Where a value comes from

Forge merges four layers. A higher layer overrides a lower one, and a blank value counts as unset, so a blank line never masks the layer beneath it.

LayerSourceHolds
4-P, ORG_GRADLE_PROJECT_, and both files below as Gradle resolved thema one-off override
3<project>/gradle.propertieswhat this artifact is and where it publishes
2~/.gradle/gradle.propertieswho you are — credentials
1forge-defaults.properties, inside the Forge jarevery default Forge applies

Layer 1 ships with the plugin and is not editable. Reading it answers "what does Forge do when I write nothing", and it changes only in a Forge release.

A one-off override needs no file:

./gradlew build -Pcom.mbseconsulting.forge.configure.spotless=false

Build configuration

Each flag switches one slice of plugin wiring. Only the literal true, in any casing, enables a slice; every other value, including false and a misspelling, reads as false. A misspelled key reaches no slice, and the configuration log names it.

KeyMeaningDefault
configure.jacocoConfigure JaCoCo and apply the jacoco pluginenabled
configure.spotlessConfigure Spotless and apply com.diffplug.spotlessenabled
configure.testingSupply the JUnit 5 stack, tag-filter test, register integrationTestenabled
configure.repositoriesAdd the release and snapshot repositoriesenabled
configure.publishingApply maven-publish, create publications and the publishAll tasksenabled
configure.codegenRun generateProfileBindings over the project's .mdzip profilesenabled
configure.dokkaConfigure Dokka and apply org.jetbrains.dokka when the project has Kotlin sourcesenabled
configure.proguardRegister the obfuscate task and route assemblePlugin through itdisabled
report.gitInclude branch, short commit SHA and a dirty marker in the report headerenabled
report.sourceEmbed uncovered source lines in the coverage section of report.htmldisabled

configure.jacoco and configure.testing belong together. Coverage enabled with testing disabled compiles no test, produces no execution data, and both JaCoCo tasks skip themselves, so the gate reports nothing. Disable both or neither.

report.source stays disabled so that no repository publishes uncovered source by inheriting a template. A project that wants the excerpts asks for them.

configure.testing=true makes Forge supply the JUnit 5 stack — the JUnit BOM 5.11.3, junit-jupiter, and junit-platform-launcher — and strip the JUnit that CATIA Magic bundles from the test classpath. See Write tests.

Kotlin compilation

KeyMeaningDefault
kotlin.daemonHeapMaximum heap of the Kotlin compile daemon, as a JVM size such as 3g or 3072m3g

Forge puts the CATIA Magic installation's jars, roughly 360, on the compile classpath. The Kotlin compile daemon otherwise inherits the Gradle daemon's heap, 512 MB unless org.gradle.jvmargs says more, which cannot hold them. The daemon then dies, the build falls back to a slower path, and it still reports BUILD SUCCESSFUL after tens of minutes. The value is a ceiling: the daemon takes only what a compile uses.

A project that sets kotlin.daemon.jvmargs, or kotlinDaemonJvmArgs in its kotlin { } block, keeps its own arguments, and Forge applies no heap. A project created from the template can delete its kotlin.daemon.jvmargs=-Xmx3g line, since kotlin.daemonHeap now supplies the same heap.

Credentials

Credentials belong in ~/.gradle/gradle.properties, outside version control. A project hosting its artifacts locally needs neither key.

KeyMeaningRule
credentials.usernameUser name for every configured Maven repositoryOptional
credentials.passwordPassword or token for the same repositoriesOptional
com.mbseconsulting.forge.credentials.username=mark-s
com.mbseconsulting.forge.credentials.password=mark0-holly1-dylan2-irvin3

One pair of credentials serves every repository. Forge applies them to the assets, release and snapshot repositories alike, and to both repositories {} and publishing.repositories {}. Omitting them leaves every repository unauthenticated, which the configuration log reports; publication then fails against a repository that requires authentication.

settings.gradle.kts reads the same two keys for the plugin repositories, through providers.gradleProperty(...), so the credentials you set here also resolve Forge itself.

Repositories

Forge configures both repositories {} and publishing.repositories {} from these keys, and applies the credentials above to each.

KeyMeaning
assets.repositoryRaw repository holding JDK, JRE, tool archives, presets, digests
releases.repositoryMaven repository for resource and plugin releases
snapshots.repositoryMaven repository for resource and plugin snapshots
com.mbseconsulting.forge.assets.repository=https://your.company.com/repository/raw-catia-magic-assets/
com.mbseconsulting.forge.releases.repository=https://your.company.com/repository/maven-catia-magic-releases/
com.mbseconsulting.forge.snapshots.repository=https://your.company.com/repository/maven-catia-magic-snapshots/

Publication accepts any Maven repository. createRegistry also reads releases.repository and snapshots.repository, and it scans a local directory, a Nexus 3 repository or an Artifactory repository. It recognizes Nexus 3 by a …/repository/<name> URL path and Artifactory by a …/artifactory/<key> path, under any context path before either segment. It fails on any other remote URL.

Resource identity

These keys describe what the project publishes and are written into the resource descriptor.

KeyMeaningRule
resource.idUnique resource identifier, forming the descriptor file nameNon-negative integer
resource.nameResource name, unique across all installed resourcesNot empty
resource.descriptionOne-line descriptionNot empty
resource.homePageResource home pageHTTP(S) URL with a registrable domain
resource.typeKind of resource, driving where the installer lists itOne of Custom Diagram, Sample, Language, Model Library, Plugin, Plugin (commercial), Profile, Template
resource.humanVersionVersion shown to usersSemantic version
resource.providerNameProvider nameNot empty
resource.providerEmailProvider contact addressValid email
resource.providerHomePageProvider home pageHTTP(S) URL with a registrable domain
resource.mdVersionMinLowest CATIA Magic version targetedA supported version (see below)
resource.mdVersionMaxHighest CATIA Magic version supportedA supported version (see below)
resource.edition.<n>Supported program edition, one key per edition, zero-indexedSee editions below

resource.mdVersionMax accepts every supported release:

2026x Refresh1, 2026x, 2024x Refresh3, 2024x Refresh2, 2024x Refresh1, 2024x.

resource.mdVersionMin accepts the narrower set a project can be built against — the releases carrying both an installable archive and a JDK behind them. Declaring compatibility with a release is not the same as building against it, so a version is nameable as a maximum before it is nameable as a minimum. The two sets coincide today; when they diverge, the failure message for resource.mdVersionMin lists the values it accepts.

Editions accept Reader, Community, Standard, Personal, Professional, Architect, Enterprise, Magic Software Architect, Magic Cyber Systems Engineer, and Magic Systems of Systems Architect. A project requires at least one.

com.mbseconsulting.forge.resource.id=7199
com.mbseconsulting.forge.resource.name=Macrodata Refinement
com.mbseconsulting.forge.resource.description=The work is mysterious and important.
com.mbseconsulting.forge.resource.homePage=https://github.lumon.com/macrodata-refinement
com.mbseconsulting.forge.resource.type=Plugin
com.mbseconsulting.forge.resource.humanVersion=8.9.27-SNAPSHOT
com.mbseconsulting.forge.resource.providerName=Mark S
com.mbseconsulting.forge.resource.providerEmail=mark.s@lumon.com
com.mbseconsulting.forge.resource.providerHomePage=https://www.lumon.com
com.mbseconsulting.forge.resource.mdVersionMin=2024x Refresh3
com.mbseconsulting.forge.resource.mdVersionMax=2026x Refresh1
com.mbseconsulting.forge.resource.edition.0=Architect
com.mbseconsulting.forge.resource.edition.1=Enterprise
com.mbseconsulting.forge.resource.edition.2=Magic Software Architect
com.mbseconsulting.forge.resource.edition.3=Magic Cyber Systems Engineer
com.mbseconsulting.forge.resource.edition.4=Magic Systems of Systems Architect

Plugin metadata

These keys populate plugin.xml. None carries a default. A project whose resource.type reads Plugin or Plugin (commercial) declares all three, exactly as it declares the resource keys; a project of any other type declares none, and a value it supplies anyway is still checked for shape.

KeyMeaningRule
plugin.classLookupClass-loader priority when the plugin uses its own loaderGlobalFirst or LocalFirst
plugin.ownClassloaderLoad the plugin in a class loader of its owntrue or false
plugin.apiVersionModeling-tool API version the plugin requiresx.y

generatePluginDescriptor writes each of the three into plugin.xml and has nothing to fall back on, so a plugin project that omits one cannot produce its descriptor. validateGradleProperties reports the omission by name.

com.mbseconsulting.forge.plugin.classLookup=GlobalFirst
com.mbseconsulting.forge.plugin.ownClassloader=false
com.mbseconsulting.forge.plugin.apiVersion=1.2

The two class-loading keys work together. ownClassloader=true gives the plugin a loader of its own, which a plugin needs when its libraries conflict with versions the tool core already carries. classLookup then decides which copy wins: LocalFirst prefers the plugin's own, GlobalFirst prefers the core's. Setting classLookup while leaving ownClassloader at false therefore changes nothing, because all plugins share one loader.

See Plugin descriptor for the attributes they produce.

Publication

KeyMeaningDefault
publication.classifierMaven classifier for the published artifactderived from resource.mdVersionMin
com.mbseconsulting.forge.publication.classifier=true

publication.classifier accepts three shapes. The value true derives the classifier from resource.mdVersionMin, which is also what an absent key does. The value false publishes without a classifier. Any other value is used verbatim.

A blank value carries no meaning of its own here, as everywhere else: Where a value comes from above drops a blank before the layers merge, so publication.classifier= reads as unset and the classifier derives. Write false to publish without one.

A resource built for 2026x Refresh1 therefore publishes as com.lumon.resources:macrodata-refinement:8.9.27:2026x-refresh1 unless the project says otherwise.

The CATIA Magic version travels as a classifier rather than as part of the version string. Maven and Gradle both read a hyphen-suffixed segment as a qualifier rather than as part of the number. A version such as 8.9.27-2026x therefore stops comparing as an equal of 8.9.27. Its position relative to that version depends on the resolver's qualifier table, so a version range or a latest.release selector can pick an artifact the build never asked for.

A classifier carries the CATIA Magic version without entering that comparison. The semantic version then identifies the resource on its own, and builds for several CATIA Magic versions share one version number.

Every artifact Forge builds carries LICENSE, NOTICE and a generated ARTIFACT-INFO. These six keys say what those files contain, and generateLegalFiles reads and validates them (see Tasks). There is no configure.legal switch: the files are artifact contents, like the resource descriptor, and a switch would create the failure the feature prevents.

KeyMeaningRuleDefault
legal.licenseThe artifact's licenceSPDX identifier or LicenseRef-<id>none, required
legal.licenseUrlWhere that licence's text is publishedHTTP(S) URL with a registrable domainnone, required
legal.copyrightHolderThe copyright holder, often the client under a client licenceNot emptynone, required
legal.classificationProduct or DeliverableExactly one of the twonone, required under an MBSE Consulting licence
legal.licenseeThe client a Deliverable was built forNot emptynone
legal.sourceProvidedWhether the delivery shipped with its sourceExactly Provided or Not providednone, required of a Deliverable
com.mbseconsulting.forge.legal.license=LicenseRef-mbseconsulting-software-1.0
com.mbseconsulting.forge.legal.licenseUrl=https://licenses.mbseconsulting.com/software/1.0.txt
com.mbseconsulting.forge.legal.copyrightHolder=MBSE Consulting
com.mbseconsulting.forge.legal.classification=Product

A Deliverable declares two keys more — the client it was built for, and whether that client received the source:

com.mbseconsulting.forge.legal.classification=Deliverable
com.mbseconsulting.forge.legal.licensee=Lumon Industries
com.mbseconsulting.forge.legal.sourceProvided=Not provided

legal.classification and legal.licensee apply only under a licence whose identifier opens with LicenseRef-mbseconsulting-. The classification states a fact about that licence and carries no meaning under anyone else's, so declaring it alongside Apache-2.0 fails the build. A Deliverable additionally requires legal.licensee, and any other classification requires that it stay unset.

legal.sourceProvided records a contractual fact the artifact does not reveal: whether the client received the source. ARTIFACT-INFO carries a Source field for every artifact except a Product, which has no client and never ships with source. Declaring Provided on a Product fails the build, because the generated file omits the field there and the declaration would reach no reader.

Under an MBSE Consulting licence a project declares legal.classification, and a Deliverable declares legal.sourceProvided as well. Neither carries a default, because each records a contractual fact the artifact does not reveal and a default would ship a statement nobody made.

A Product is asked only for the classification. It has no client, so nobody can have received its source: Provided fails the build there, ARTIFACT-INFO omits the Source field, and a required declaration would leave one legal value that the generated file discards. The decision the pair exists to force is made at legal.classification. A Product that declares Not provided anyway stays valid; it is simply not required to.

Under any other licence a project declares neither: legal.classification fails the build, because the classification states a fact about a licence family it is not under, while legal.sourceProvided is merely not required, because nothing rejects it outside that family.

legal.sourceProvided and report.source answer different questions and neither reads the other. The first states what the client received; the second decides whether one generated report.html embeds uncovered source excerpts. Set both where both apply.

legal.licenseUrl is declared rather than looked up. A lookup table pairing every identifier with a URL would need extending whenever a repository adopts one the table omits, which surfaces as a build error in a repository that did nothing wrong.

A repository also supplies a LICENSE in its root, and a NOTICE where it has third-party attributions to pass on. Under a licence whose identifier carries the LicenseRef-mbseconsulting- prefix, the repository's LICENSE text must contain the declared identifier, and a mismatch fails the build. A blank NOTICE fails the build; an absent one does not, because an empty one converts nothing into an obligation on every downstream redistributor. Never commit an ARTIFACT-INFO: the build generates it, and a checked-in copy fails the build.

A spotless-header.txt may carry $legal.license, $legal.licenseUrl and $legal.copyrightHolder beside the provider tokens $resource.providerName, $resource.providerEmail and $resource.providerHomePage. Each token is optional, per repository and per line: a header that never mentions any of them renders unchanged, exactly as a fully hardcoded header did before these tokens existed. Where a header does mention one, Forge substitutes the corresponding legal.* key from this section into the Kotlin sources Spotless formats, into the sources generateProfileBindings generates, and into the stamped resourceDescriptor.xml and plugin.xml that generateResourceDescriptor and generatePluginDescriptor produce.

A header may also carry a year token, spelled either $YEAR or $year. Forge substitutes both with the build year. Spotless resolves $YEAR itself in the Java and Kotlin sources it formats, but it never sees the generated XML, so Forge resolves the token again on every path it stamps. A header that hardcodes its year mentions neither token and renders unchanged.

Extension properties

Two settings have no Gradle property and are assigned in the forge { } block, because a Gradle property carries a string and these carry richer values. externalZips names the vendor resource and plugin archives to index — the ones Dassault ships, which the project did not build:

forge {
    externalZips.from(fileTree("path/to/your/folder/"))
}

externalZips is a ConfigurableFileCollection, so it takes anything Gradle's files(...) accepts. Use fileTree(...) to sweep a directory, or name archives individually:

forge {
    externalZips.from(
        file("vendor/sysml-2026.1.0.zip"),
        file("vendor/uaf-2026.1.0.zip"),
    )
    // Add to what is already declared:
    externalZips.from(fileTree("vendor/extra/") { include("**/*.zip") })
}

createExternalZipIndex parses each archive and writes external-index.json, which createRegistry then merges with the repositories to produce registry.json. Leaving externalZips empty is normal for a project that only publishes its own resource. See Publish raw assets.

The second setting is the sources { } block, which declares what zipSources packages; see Package the project sources.

The block also exposes distributionZips, which Forge populates from this project's own build/distributions output. It is read-only in practice — the plugin fills it, and a project has no reason to assign it.

Plugin-managed state

Three keys record where the environment tasks installed things. Forge writes them to dev-env/user.properties and rewrites them on each install, so a project neither commits them nor edits them by hand. They carry no com.mbseconsulting.forge. prefix.

KeyWritten byMeaning
catia.magic.installation.directoryinstallCatiaMagicRoot of the installed CATIA Magic
jdk.installation.directoryinstallJdkRoot of the installed JDK
jre.installation.directoryinstallJreRoot of the installed JRE

catia.magic.installation.directory also gates the integrationTest task: Forge registers it only once an installation path exists.

jdk.installation.directory names the JDK every Java task runs on: compilation, unit tests, Javadoc and every JavaExec task except integrationTest, which runs on the JRE. A project may point the key at a JDK installed elsewhere; Forge identifies it from its release file, and fails every Java task when its major version is not the one resource.mdVersionMin needs. Forge ignores a path under ~/.mbseconsulting-forge/jdk/ that names another CATIA Magic release, and uses the directory for resource.mdVersionMin instead.

On this page