Forge
Tutorials

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-resource

The template already carries the parts you would otherwise write by hand:

FileWhat it holds
settings.gradle.ktsThe pluginManagement block locating Forge, with credentials read from Gradle properties
build.gradle.ktsThe plugin apply and example dependency declarations — Forge applies Spotless and JaCoCo itself
gradle.propertiesRepository 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-snapshots

4. 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=true

Properties 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.2

Two 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.zip

installJdk 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 installCatiaMagicDependencies

The 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 assemble

build/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 integrationTest

You write no test suite and no shutdown code — see Write tests.

A full build is:

./gradlew build

That 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 publishAll

The 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

On this page