Forge
How-to guides

Install CATIA Magic

Install a JDK and a CATIA Magic release with the environment tasks.

Forge installs the toolchain a project needs into its own dev-env folder, which is excluded from version control. Nothing is installed system-wide, so several projects on one machine can target different CATIA Magic versions.

These tasks read com.mbseconsulting.forge.resource.mdVersionMin, so set it before running them.

Install the JDK

./gradlew installJdk

The task picks the JDK matching resource.mdVersionMin, downloads it from the assets repository, and extracts it. JDK and JRE land in ~/.mbseconsulting-forge/jdk and ~/.mbseconsulting-forge/jre by default.

installJdk then records the directory as jdk.installation.directory in dev-env/user.properties. Compilation, unit tests, Javadoc and every JavaExec task run on that JDK, so Gradle never searches the machine for one. A build that needs the JDK before installJdk has run fails, naming installJdk as the fix.

installJre installs the JRE that integrationTest runs on, and records it as jre.installation.directory.

Find an available version

./gradlew listCatiaMagicVersions
Archive                                              Preset  AI-docs
---------------------------------------------------  ------  -------
Cameo_Systems_Modeler_2024x_Refresh2_HF1_no_install    yes     no
Cameo_Systems_Modeler_2024x_Refresh3_no_install        yes     no
Cameo_Systems_Modeler_2026x_HF2_no_install             yes     yes

The task lists what the assets repository holds, and whether each archive has a user preset and an AI-docs digest. Copy an archive name into the next command.

Install the tool

./gradlew installCatiaMagic -Pfile=Cameo_Systems_Modeler_2024x_Refresh3_no_install.zip

The archive extracts into the project's dev-env folder. The user preset installs with it, so the licence server is already configured when you first launch the tool.

Two flags control the optional parts:

FlagEffect
-PuserPreset=falseSkip the user preset
-PaiDocs=falseSkip the AI-docs digest

The AI-docs digest

installCatiaMagic also fetches the AI-docs digest for that build, when one has been published, and unpacks it to dev-env/ai-docs/:

dev-env/
  Cameo_Systems_Modeler_2026x_HF2_no_install/   the tool
  ai-docs/
    INDEX.md                                    two-axis lookup table
    reference/api|guide/                        per-version, ships with the tool

The digest renders the Developer Guide and the Open API JavaDoc as markdown sized for an AI context window. A digest exists only for the builds that have been ingested, so it is often absent — that never fails the install, and you simply work without it. See The AI-docs digest for why it travels with the tool.

Verify the result

./gradlew verifyJdk verifyJre

Both tasks run as part of check, so a normal build already covers them.

Next

Declare dependencies to install the resources and plugins your project builds against.

On this page