Building and Running

In order to get started contributing to Tortoise, you'll need to get your system setup to do the building of the libraries (JVM and Javascript) and handle the running of tests. You'll need to install some tools, prep the repository, get GraalVM setup, and then you should be ready to hack away.

Tools

• Install Git, which is our source control client.

• Install SBT, which is our build and testing tool.

• Install Node and NPM, which is used by the the Tortoise engine project. Version 14 is required and 16 recommended.

• Install SDKMAN!, which is used to manage the GraalVM installation.

• Install the GraalVM version Tortoise pins. From the root of the repository:

  sdk env install
  

  This reads the .sdkmanrc file in the repository root and installs the JDK named there -- currently GraalVM Community Edition 25.0.2 (Java 25), which is the Java runtime and JavaScript environment used by Tortoise. The sbt.sh script applies the same .sdkmanrc, so the version only ever has to be changed in that one file.

Repository Setup

• Clone the repository: git clone https://github.com/NetLogo/Tortoise.git
• Navigate into the root of the Tortoise repository directory, cd Tortoise.
• Run git submodule update --init to make sure the models submodule is initialized.

GraalVM Setup

Tortoise uses the GraalVM SDK in order to use the Graal Javascript compiler and runtime to test the Javascript code that Tortoise generates. The sbt.sh script handles selecting the correct GraalVM version automatically via SDKMAN!, using the .sdkmanrc file in the repository root.

• In your terminal of choice, browse to the Tortoise repository folder and run ./sbt.sh to start the sbt build tool for Tortoise.
  • Run ./sbt.sh and not sbt. The ./sbt.sh shell script uses SDKMAN! to activate GraalVM and handles some pathing and other issues that you probably don't want to deal with.
  • If you would rather run sbt directly, run sdk env first to apply .sdkmanrc to your shell. (You can also set sdkman_auto_env=true in ~/.sdkman/etc/config to have SDKMAN! apply it whenever you cd into the repository.) Note that you would still be missing the node/npm pathing that sbt.sh sets up.

In the sbt.sh console you started, try running compilerJVM/compile or netLogoWeb/testOnly *TestReporters to confirm everything is working.

Running on the wrong JDK

Running the tests on a non-GraalVM JDK does not fail with a clear error, which makes this worth recognizing: Graal's Javascript engine silently falls back to an interpreter (no JVMCI means no JIT compilation), so everything still builds and the tests still pass -- they just run roughly 18x slower. A test that normally takes 40 seconds takes 12 minutes, which reads as a hang rather than a misconfiguration.

The tell is this warning near the start of the test output:

[engine] WARNING: The polyglot engine uses a fallback runtime that does not support runtime compilation to native code.
The following cause was found: JVMCI is not enabled for this JVM.

If you see it, you are on the wrong JDK -- run ./sbt.sh (or sdk env) rather than trying to make sense of the slowness.

GraalVM Versions

We try to keep Tortoise up-to-date with the GraalVM releases, but sometimes there are breaking changes that we haven't accommodated yet. If you have problems getting things working you may try downgrading to a version that was known to work; change the java= line in .sdkmanrc and both sbt.sh and sdk env will follow. As of March 2026, Tortoise has been updated to work with GraalVM Community Edition 25.0.2, Java 25 (SDKMAN! identifier: 25.0.2-graalce).

Next Steps

Read over the Tortoise Project Setup and the Architecture for necessary background information. Also, check out the Tortoise Tests you can run to validate your changes.