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.
| Layer | Source | Holds |
|---|---|---|
| 4 | -P, ORG_GRADLE_PROJECT_, and both files below as Gradle resolved them | a one-off override |
| 3 | <project>/gradle.properties | what this artifact is and where it publishes |
| 2 | ~/.gradle/gradle.properties | who you are — credentials |
| 1 | forge-defaults.properties, inside the Forge jar | every 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=falseBuild 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.
| Key | Meaning | Default |
|---|---|---|
configure.jacoco | Configure JaCoCo and apply the jacoco plugin | enabled |
configure.spotless | Configure Spotless and apply com.diffplug.spotless | enabled |
configure.testing | Supply the JUnit 5 stack, tag-filter test, register integrationTest | enabled |
configure.repositories | Add the release and snapshot repositories | enabled |
configure.publishing | Apply maven-publish, create publications and the publishAll tasks | enabled |
configure.codegen | Run generateProfileBindings over the project's .mdzip profiles | enabled |
configure.dokka | Configure Dokka and apply org.jetbrains.dokka when the project has Kotlin sources | enabled |
configure.proguard | Register the obfuscate task and route assemblePlugin through it | disabled |
report.git | Include branch, short commit SHA and a dirty marker in the report header | enabled |
report.source | Embed uncovered source lines in the coverage section of report.html | disabled |
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
| Key | Meaning | Default |
|---|---|---|
kotlin.daemonHeap | Maximum heap of the Kotlin compile daemon, as a JVM size such as 3g or 3072m | 3g |
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.
| Key | Meaning | Rule |
|---|---|---|
credentials.username | User name for every configured Maven repository | Optional |
credentials.password | Password or token for the same repositories | Optional |
com.mbseconsulting.forge.credentials.username=mark-s
com.mbseconsulting.forge.credentials.password=mark0-holly1-dylan2-irvin3One 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.
| Key | Meaning |
|---|---|
assets.repository | Raw repository holding JDK, JRE, tool archives, presets, digests |
releases.repository | Maven repository for resource and plugin releases |
snapshots.repository | Maven 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.
| Key | Meaning | Rule |
|---|---|---|
resource.id | Unique resource identifier, forming the descriptor file name | Non-negative integer |
resource.name | Resource name, unique across all installed resources | Not empty |
resource.description | One-line description | Not empty |
resource.homePage | Resource home page | HTTP(S) URL with a registrable domain |
resource.type | Kind of resource, driving where the installer lists it | One of Custom Diagram, Sample, Language, Model Library, Plugin, Plugin (commercial), Profile, Template |
resource.humanVersion | Version shown to users | Semantic version |
resource.providerName | Provider name | Not empty |
resource.providerEmail | Provider contact address | Valid email |
resource.providerHomePage | Provider home page | HTTP(S) URL with a registrable domain |
resource.mdVersionMin | Lowest CATIA Magic version targeted | A supported version (see below) |
resource.mdVersionMax | Highest CATIA Magic version supported | A supported version (see below) |
resource.edition.<n> | Supported program edition, one key per edition, zero-indexed | See 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 ArchitectPlugin 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.
| Key | Meaning | Rule |
|---|---|---|
plugin.classLookup | Class-loader priority when the plugin uses its own loader | GlobalFirst or LocalFirst |
plugin.ownClassloader | Load the plugin in a class loader of its own | true or false |
plugin.apiVersion | Modeling-tool API version the plugin requires | x.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.2The 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
| Key | Meaning | Default |
|---|---|---|
publication.classifier | Maven classifier for the published artifact | derived from resource.mdVersionMin |
com.mbseconsulting.forge.publication.classifier=truepublication.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.
Legal
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.
| Key | Meaning | Rule | Default |
|---|---|---|---|
legal.license | The artifact's licence | SPDX identifier or LicenseRef-<id> | none, required |
legal.licenseUrl | Where that licence's text is published | HTTP(S) URL with a registrable domain | none, required |
legal.copyrightHolder | The copyright holder, often the client under a client licence | Not empty | none, required |
legal.classification | Product or Deliverable | Exactly one of the two | none, required under an MBSE Consulting licence |
legal.licensee | The client a Deliverable was built for | Not empty | none |
legal.sourceProvided | Whether the delivery shipped with its source | Exactly Provided or Not provided | none, 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=ProductA 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 providedlegal.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.
| Key | Written by | Meaning |
|---|---|---|
catia.magic.installation.directory | installCatiaMagic | Root of the installed CATIA Magic |
jdk.installation.directory | installJdk | Root of the installed JDK |
jre.installation.directory | installJre | Root 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.