Your first resource
Build and publish your first CATIA Magic resource, from a cloned template to a published zip.
This tutorial takes you from an empty machine to a published CATIA Magic resource. Follow it once, in order. Later work is better served by the how-to guides.
The tutorial assumes your organisation's repositories already hold the raw assets and the vendor resources. If they do not, an administrator runs Bootstrap the repositories first — once, for everyone.
1. Prepare your machine
Install Git and an IDE, and put your repository credentials in ~/.gradle/gradle.properties.
Set up your machine covers both, per operating system.
2. Create the project from the template
magic-forge-template is a working Forge project. Start from it rather than from an empty
directory:
gh repo create my-resource --template mbseconsulting/magic-forge-template --private --clone
cd my-resourceThe template already carries the parts you would otherwise write by hand:
| File | What it holds |
|---|---|
settings.gradle.kts | The pluginManagement block locating Forge, with credentials read from Gradle properties |
build.gradle.kts | The plugin apply and example dependency declarations — Forge applies Spotless and JaCoCo itself |
gradle.properties | Repository URLs, placeholder resource metadata, and any build flag the template overrides from Forge's defaults |
src/main/assembly/ | The profiles, modelLibraries, templates, samples, data and plugins folders |
The template's macrodata-renaming-example branch carries a worked resource with a plugin,
profiles and tests.
One Git repository holds one resource, and that resource holds at most one plugin jar.
3. Point it at your repositories
The template points at MBSE Consulting's Nexus. If yours differs, change the URLs in
settings.gradle.kts — Gradle resolves the plugin itself before reading your build script, so those
two live there — and the three repository URLs in gradle.properties:
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-snapshots4. Choose the build wiring
Forge ships these defaults, so the template writes none of them: configure.jacoco,
configure.spotless, configure.testing, configure.repositories, configure.publishing,
configure.codegen and configure.dokka default on; configure.proguard defaults off. Write a flag only to change it from its default — only the
literal true, in any casing, enables one; anything else, including false, disables it.
com.mbseconsulting.forge.configure.proguard=trueProperties documents every flag, its default, and the four layers Forge merges to resolve one.
5. Describe your resource
Replace the template's placeholders — Your Resource Name, 12345, and the rest. These properties
become the resource descriptor and plugin.xml, so you write no XML:
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
com.mbseconsulting.forge.plugin.classLookup=GlobalFirst
com.mbseconsulting.forge.plugin.ownClassloader=false
com.mbseconsulting.forge.plugin.apiVersion=1.2Two of these drive more than the descriptor. resource.humanVersion decides whether publication
targets snapshots or releases. resource.mdVersionMin selects the JDK, the toolchain, and the Maven
classifier, so set it to the version you actually build against.
Properties documents every key and its validation rule.
6. Install the toolchain
./gradlew installJdk
./gradlew listCatiaMagicVersions
./gradlew installCatiaMagic -Pfile=Cameo_Systems_Modeler_2024x_Refresh3_no_install.zipinstallJdk picks the JDK matching resource.mdVersionMin, and every Java task in the build runs
on it. listCatiaMagicVersions shows what the assets repository holds; copy an archive name
into the third command. CATIA Magic installs into the project's dev-env folder, excluded from
version control, together with its user preset and — when one exists — its
AI-docs digest.
Install CATIA Magic has the details.
7. Declare what you depend on
dependencies {
implementation("com.fasterxml.jackson.core:jackson-databind:2.15.2")
catiaMagic("com.3ds.resources:product-line-engineering:2024.3.0")
catiaMagic("com.3ds.plugins:sysml:2024.3.0")
}Then install them:
./gradlew installCatiaMagicDependenciesThe catiaMagic declarations do double duty: they install the resources locally, and they populate
the requiredResource and required-plugin nodes of the generated descriptors. You never declare
the CATIA Magic API itself — Forge injects it. See
Declare dependencies.
8. Build the resource
Put your profiles, model libraries, templates and samples under src/main/assembly/, in the folder
each kind belongs in, and write plugin code under src/main/kotlin or src/main/java.
./gradlew assemblebuild/distributions/ now holds the resource zip you give users, and the plugin zip you publish.
Tag your tests @Tag("UnitTest") or @Tag("IntegrationTest") and run them:
./gradlew test
./gradlew integrationTestYou write no test suite and no shutdown code — see Write tests.
A full build is:
./gradlew buildThat one command assembles both archives, runs the validators and the unit tests, and produces and
gates the coverage report. It runs the integration tests too once you have written one; until then
integrationTest skips, so the build takes no licence.
9. Publish
./gradlew createRegistry
./gradlew assemble
./gradlew publishAllThe first run takes two commands because publications are created from the JSON that
createRegistry and assemble write, and Gradle configures publications before any task runs.
Later builds publish in one pass. Publish a resource explains the
mechanism and the snapshot-against-release split.
Where to go next
- Generate profile bindings — typed Kotlin access to the profiles you ship
- The dependency model — why Forge works this way