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 tool.
• Install Node and NPM, which is used by the the Tortoise engine project.
• Install Yarn, which is the package manager used by the Tortoise engine project.
• Install GraalVM, which is the Java runtime and Javascript environment used by Tortoise. Community Edition should work fine.
  • A good place to install it is alongside whatever other Java JDKs you may have installed.
  • Example install location on macOS: /Library/Java/JavaVirtualMachines/graalvm-ce-1.0.0-rc12/

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.

For more info on building and testing Tortoise, see the Tortoise wiki.

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. To setup the GraalVM SDK to compile and test the Tortoise projects:

• Add a GRAAL_HOME environment variable for the path that you installed GraalVM to, with the /Contents/Home subfolder appended.
  • Example ~/.bash_profile entry on macOS: export GRAAL_HOME='/Library/Java/JavaVirtualMachines/graalvm-ce-1.0.0-rc12/Contents/Home'
• In your terminal of choice, browse to the Tortoise repository folder and run ./sbt.sh to start the sbt build tool for Tortoise using the GraalVM specified by your GRAAL_HOME variable.
• Launch SBT by running ./sbt.sh.
  • Run ./sbt.sh and not sbt. The ./sbt.sh shell script handles some pathing and other issues that you probably don't want to deal with.

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

GraalVM Versions

GraalVM is not yet at a "stable" 1.0 release. As such things change and break between release candidate versions. We'll try to keep Tortoise up-to-date with their releases, but if you have problems getting things working you may try downgrading to a release candidate that was known to work. As of February 2019, Tortoise has been updated to work with GraalVM RC12.

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.