Installing the development version

This page explains how to set up an Eclipse workspace to develop GAMA from its sources. The development version lives in the main branch of gama-platform/gama. Changes made in other branches only reach a GAMA release through a reviewed pull request.

Most of the setup is automated by the GAMA Developer Tools, an Eclipse plugin that clones the sources, imports the projects, checks the workspace, launches GAMA and repairs generated code. This page covers both guided and manual setup. The complete reference of the tools is the GAMA Developer Tools guide.

1. Prepare the environment

Component	Version	Notes
IDE	Eclipse IDE for Java and DSL Developers 2026-03 or newer	Runs on Java 21 or newer. Needs JDT, PDE and Xtext/MWE2.
JDK used to compile and launch GAMA	JDK 25 (full JDK, not a JRE)	For instance Eclipse Temurin 25. GAMA launches use --enable-preview, so the JDK must be exactly Java 25.

1. Download and install Eclipse IDE for Java and DSL Developers 2026-03. Eclipse itself and the GAMA annotation processor (gama.processor) use Java 21-compatible bytecode: there is no need to change the Java runtime of Eclipse.
2. If the Plug-in Development Environment (PDE) is missing, install it with Help > Install New Software... from the Eclipse 2026-03 update site https://download.eclipse.org/releases/2026-03/.
3. Install a separate full JDK 25. The JDK 25 compiler produces Java 21-compatible bytecode for the annotation and processor projects according to their checked-in project settings.
4. In Eclipse, open Preferences > Java > Installed JREs, add the JDK 25 and make it the default. Then, in Installed JREs > Execution Environments, associate it with both JavaSE-25 and JavaSE-21. JavaSE-21 is used by gama.annotations, which keeps a Java 21 compatibility target; JDK 25 can compile for both. Keep the compiler settings checked in with the projects.

2. Install the GAMA Developer Tools

1. Choose Help > Install New Software... and add the update site https://gama-platform.org/gama.devtools/.
2. Select GAMA Developer Tools, finish the installation and restart Eclipse.

Install them in the Eclipse IDE used for development, not in a GAMA application. A GAMA menu and a GAMA toolbar are added to Eclipse. Later updates are installed with GAMA > Update GAMA tools...; the menu item reads Update GAMA tools... (update available) when a newer version is published.

3. Recommended: use Get started...

After restarting Eclipse, choose GAMA > Get started..., or accept the startup prompt in a workspace without a gama.core project. A closed gama.core project also suppresses the prompt. Declining it without selecting Do not ask again in this workspace allows it to appear at the next startup. The prompt can be re-enabled in Preferences > GAMA Developer Tools; the menu remains available. This guided route checks prerequisites, helps register JDK 25, opens the source installers, provides an explicit clean-and-build step, and lets you create or use a GUI launch configuration.

1. Check Eclipse: review the version (2026-03 or newer), Java runtime (21+), JDT, PDE, Xtext/MWE2 and memory checks. The wizard links to installation help; it does not install Eclipse components or change eclipse.ini. A heap of about 2 GB (-Xmx2048m after -vmargs) is recommended.
2. Configure JDK 25: select a detected full JDK 25 or browse to one. Next registers it. Making it the workspace default and associating it with JavaSE-25 and JavaSE-21 are selected by default. Eclipse continues running on its existing JVM; downloading/installing the JDK is manual.
3. Install sources: the page opens the core, graphical editor and community installers. Required core projects gama.annotations, gama.processor and gaml.grammar cannot be deselected when missing. Review checkout, branch, project, working-set and optional preference choices. This page defers the installer-scheduled clean/build; Eclipse automatic building may still occur.
4. Clean and build: click Clean and build now to save editors, refresh, repair plugin settings, clean/rebuild and report generated-addition, build and target-platform issues. A completed build attempt lets you continue even if errors remain; review the reported problems before proceeding.
5. Run GAMA: select Run, Debug or configuration-only. The wizard uses the associated GUI launch or can generate a fresh default while retaining the old configuration. Launch validation and a cancellable workspace refresh happen before a requested launch.

The wizard is interactive and does not automatically download JDKs, install Eclipse components, run the build, or launch GAMA. The running Eclipse installation is the PDE target; no GAMA .target file needs to be imported. Missing bundles are diagnosed with links to Install New Software... and Target Platform, but the wizard does not install them or create/activate a target definition.

4. Use the individual source installer

The guided wizard is recommended. You can also use the source installer directly from the GAMA menu: GAMA > Install GAMA sources > Install core plugins....

1. Repository. Choose a checkout directory, the repository URL and the branch. The defaults are https://github.com/gama-platform/gama.git and main. Next clones the repository, or fetches and fast-forwards an existing checkout. Git is embedded (JGit): no separate Git installation is needed. An existing checkout must be clean and fast-forwardable: the wizard refuses dirty repositories, unfinished Git operations and branches with local commits, and never stashes, resets or overwrites local changes.
2. Projects. The projects listed in gama.parent/pom.xml, plus gama.parent, are preselected (unless already imported). gama.annotations, gama.processor and gaml.grammar are required: when they are not in the workspace yet, they are always imported and cannot be deselected. Projects are imported in place (not copied into the workspace) and shared with EGit.
3. Options.
   • Working sets: additive working sets defined in the developer tools (utils/Project sets for Gama.psf; the core installation also preselects an EXPORT working set), with an option to show working sets as roots in the Project and Package Explorers.
   • Preferences (opt-in): Eclipse Preferences for Gama.epf, Cleanup rules for Gama.xml and Code formatter rules for Gama.xml. The Eclipse preferences also contain Java compiler defaults: review this choice before importing them.
   • Close gama.parent (recommended, selected by default): disables the Maven compilation of the parent project inside Eclipse. It does not remove anything from the checkout.
4. Finish imports the projects, applies the selected settings, then schedules a workspace refresh, a clean and a full build. The first build takes a while: follow it in the Progress view.

Cancelling or a failure keeps what has already been cloned or imported; nothing is rolled back.

5. Check the workspace

When the build is finished, choose GAMA > Check workspace.... It reports missing workspace projects, target-platform bundles required by the GUI product, plugin configuration problems (annotation processing, gaml/ source folder, plugin.xml, encoding...) and the absence of a compatible JDK 25. After confirmation, it can repair the fixable plugin settings or open the core source installer. Nothing is changed without confirmation.

6. Run GAMA

Use GAMA > Run GAMA > Run UI (or the blue Run icon of the GAMA toolbar).

• First launch. Run GAMA > Configure... opens: select an existing Eclipse Application launch configuration or generate a default one (GAMA - GUI, GAMA - Headless, GAMA - Tests) using the registered JDK 25. Defaults are generated from gama.product/gama.product (or gama.product/gama.headless.product). Edit configuration... opens the standard Eclipse launch properties (memory, arguments, plugins); Restore generated defaults... creates a fresh configuration and keeps the old one.
• Other launches. The same submenu offers Debug UI, Run headless / Debug headless (which ask for the headless arguments, for instance -batch experimentName "/path/model.gaml") and Run tests (a headless launch with -test).
• Refresh before launch. Every launch first refreshes the whole workspace from disk, as a cancellable background job. Cancelling it, or a refresh failure, prevents the launch. If projects required by the product are missing or closed, the core installer is opened instead.
• Exit code 42. When the GAMA UI exits with status 42 (fatal failure of the mandatory GAML initialization, GamaBundleLoader.EXIT_GAML_INITIALIZATION_FAILED in gama.api), a dialog proposes Clean and Relaunch, Clean Only or Ignore. Recovery runs Clean GAMA plugins; the relaunch (in the original run or debug mode) only happens if every GamlAdditions class was regenerated without build errors.

Keeping up to date

To update the sources, run GAMA > Install GAMA sources > Install core plugins... again on the same checkout: the wizard fetches and fast-forwards it (only fast-forward updates are performed), and lists new projects to import. Commit, stash or reconcile local changes first (with EGit or the command line). You can also pull with any Git client. After an update, run GAMA > Clean GAMA plugins.

Graphical editor and community plugins

The Install GAMA sources submenu provides two other variants of the same wizard:

• Install graphical editor... uses gama-platform-plugins/gama.graphical.modeling, branch GAMA_2026-06, with all its projects preselected.
• Install community plugins... lists the repositories of the gama-platform-plugins organization that have a GAMA_2026-06 branch with Eclipse projects. Load the list and select the projects explicitly: only the repositories containing selected projects are cloned (one subdirectory per repository), and the projects are added to the COMMUNITY working set. Repositories without that branch are shown as unavailable.

Troubleshooting

Problem	What to do
Errors in many projects, missing GamlAdditions, stale generated code	GAMA > Clean GAMA plugins (Cmd+B on macOS, Ctrl+B on Windows/Linux). It refreshes the workspace, repairs the plugins configuration, deletes the generated gaml/ folders and runs a clean and full build, then checks that every GamlAdditions.java was regenerated. Remaining problems appear in the Problems view, with quick fixes. Clean... in the GAMA context menu does the same for the selected plugins only.
You modified gama.processor or gama.annotations	GAMA > Repair GAMA plugins > Rebuild annotation processor regenerates gama.processor/gama.processor.jar from Generate Processor.jardesc. Then clean the GAMA plugins.
You modified the GAML grammar	GAMA > Repair GAMA plugins > Regenerate Xtext grammar runs gaml.grammar/src/gaml/grammar/generator/Generate_GAML_Artefacts.mwe2. gaml.grammar, gaml.compiler and gama.ui.editor must be open.
Bundles reported missing by Check workspace... or at launch	The installer does not resolve the PDE target platform. Review Preferences > Plug-in Development > Target Platform, and check that all the projects required by gama.product/gama.product are imported and open. The Maven build resolves the Eclipse bundles from https://download.eclipse.org/releases/2026-03/.
"No JDK 25" or launch failures about preview features	Register a full JDK 25 in Installed JREs, associate it with JavaSE-25 and JavaSE-21, and select it in the launch configuration.
A problem with the developer tools themselves	GAMA > Report an issue... opens a new issue in gama-platform/gama.devtools.

Manual alternative (without developer tools)

For this route, use the Eclipse and JDK requirements in section 1, skip the developer-tools installation in section 2, and set up the workspace by hand:

1. Clone https://github.com/gama-platform/gama.git (branch main) with EGit or any Git client.

2. Import the projects with File > Import... > General > Existing Projects into Workspace, selecting the root of the clone (projects are imported in place). Import at least gama.annotations, gama.processor, gaml.grammar and the projects listed in gama.parent/pom.xml, and close gama.parent.

3. Register a full JDK 25 under Preferences > Java > Installed JREs, set it as the default, and associate it with JavaSE-25 and JavaSE-21 under Execution Environments. Keep the projects' checked-in compiler settings, .classpath, .factorypath, plugin.xml and build.properties. Enable automatic building and run Project > Clean... on all projects. The annotation processor JAR is gama.processor/gama.processor.jar; if it needs rebuilding, open gama.processor/Generate Processor.jardesc and use Create JAR, then clean the projects. Generated sources belong in gaml/; never edit them manually.

4. To build a distribution from the command line, use Maven 3.9 with JAVA_HOME pointing to JDK 25. Check that mvn -version reports Java 25, then build in this order:

   mvn -f gama.annotations/pom.xml clean install
   mvn -f gama.processor/pom.xml clean install
   mvn -f gama.parent/pom.xml clean install
   

   The annotations and processor retain Java 21-compatible bytecode; the rest of GAMA targets Java 25. Distributions are written to gama.product/target/products. See Creating a release of GAMA for the developer-tools build alternative.

5. Use the running Eclipse installation as the PDE target and install any missing target bundles. Launch GAMA by opening gama.product/gama.product and using Launch an Eclipse application in its Overview tab, with a JDK 25 runtime and the product's VM arguments including --enable-preview.

Generated launch configurations, workspace checks, automatic repairs and the exit-42 recovery are then not available.