Forge
How-to guides

Generate profile bindings

Generate typed Kotlin bindings from the profiles a resource ships.

generateProfileBindings reads every .mdzip under src/main/assembly/profiles/ and emits Kotlin bindings for the profiles it finds, so code reaches stereotypes and tags through typed declarations rather than string lookups.

Each stereotype gets a predicate and, where it carries tags, a typed view. Each profile enumeration becomes a Kotlin enum.

Switch generation on or off

Generation is on by default. A project that ships a .mdzip profile under src/main/assembly/profiles/ gets bindings, and a project that wants none sets:

com.mbseconsulting.forge.configure.codegen=false

The generated code calls the runtime in Anvil, published as two artifacts: a resource carrying the profile content, and a plugin carrying the runtime jar. Declare both on the catiaMagic configuration and install them:

dependencies {
    catiaMagic("com.mbseconsulting.resources:anvil:4.0.0:2026x-refresh1@zip")
    catiaMagic("com.mbseconsulting.plugins:anvil:4.0.0:2026x-refresh1@zip")
}
./gradlew installCatiaMagicDependencies

That installs both into your CATIA Magic installation — the plugin under plugins/com.mbseconsulting.anvil/ — and Forge injects the runtime jar onto compileOnly from there, the same as every other jar under the installation's lib/ and plugins/ folders — no further declaration reaches the runtime. See Declare dependencies.

The generator itself is part of Forge, so the plugin version selects it and the project pins nothing extra. A project that ships no .mdzip sees the task as NO-SOURCE and builds normally.

Switching the key to false skips the task rather than cleaning its output. A project that already generated bindings keeps them on disk, and they keep compiling, until clean removes them.

Where the output goes

Generated code lands in build/generated/forge/profiles/ and is registered on the main source set, so the IDE indexes it as a generated source root and compileKotlin picks it up without an explicit dependency.

The output stays under build/ for its whole life. Never commit it, never copy it into src/. It regenerates whenever a .mdzip changes, when the CATIA Magic installation changes, and also when spotless-header.txt or the provider and resource identity that the license header substitutes changes.

Each generated file carries the license header built from the project's spotless-header.txt, the same header Spotless writes into src/. The task applies the header itself rather than through Spotless. The output directory belongs to the task, so a Spotless pass over it would rewrite files Gradle already recorded, forcing regeneration on every build. The task warns and leaves the sources unstamped when a project ships no spotless-header.txt, or when resource.providerName, resource.providerEmail, resource.providerHomePage, resource.name, legal.license, legal.licenseUrl or legal.copyrightHolder is unset. Neither gap fails the build.

Requirements

Generated bindings are Kotlin, so they compile only where the Kotlin plugin is applied. A project that ships a profile while carrying no Kotlin source gets a warning at configuration time, since nothing would compile the bindings. Add a Kotlin source under src/main/kotlin.

The task runs in the Gradle daemon, so it forks no JVM and pins no generator version. It reads the installation named by catia.magic.installation.directory to type the bindings, as the next section describes, and still generates on a machine that has none.

Unresolved metaclasses

A stereotype extends a UML metaclass, and the emitted binding names the CATIA Magic type for that metaclass. The plugin builds the metaclass table by scanning the entry names of the jars under the installation's lib/ and plugins/, so the table always describes the version the project compiles against.

A metaclass the scan cannot resolve is emitted as Element, the common supertype, rather than guessed into a package. The task reports how many names degraded and lists each one at --info. A degraded binding still compiles and still finds the stereotype; it types the element less precisely, so the calling code narrows the type itself. A machine with no installation configured resolves nothing and degrades every name.

Reserved tag names

The generated view class names each property after the tag it binds, so a tag name reaches Kotlin as a declaration beside the accessors that read and write it. A tag named after the enumeration typing it, after the profile object, or after Project therefore carries a name those accessors also reference. The generator resolves each of those itself, by reaching the shadowed name through its fully qualified form, and a profile carrying no such tag generates unchanged output. No modelling change is needed.

Two names the generator cannot reach around, and rejects, naming the profile, the stereotype and the tag:

A tag namedWhy it is rejected
elementThe view already declares element for the stereotyped element itself, and the two declarations collide.
the first segment of the generated package, usually comA qualified name opens with that segment, so the tag shadows the way around every other collision as well.

Limitations

Version 1 of the generator does not support a derived, ordered or non-unique tag. It detects each one and fails the build, naming the profile, the stereotype and the tag, rather than emitting a binding that compiles and then misbehaves.

On this page