Skip to content

Building and Running

Jump to bottom Edit New page
jeremy.baker@northwestern.edu edited this page Nov 22, 2022 · 7 revisions

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 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-java17-22.2.0/
    • You will need to run gu install js in the bin folder of that install to install the JavaScript language package (it used to come bundled).

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. 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-java8-20.0.0/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.sh console you started, try running compilerJVM/compile or netLogoWeb/testOnly *TestReporters to confirm everything is working.

If you are running GraalVM on macOS Catalina and may get an error such as " cannot be opened because the developer cannot be verified". You will need to run a command to remove the quarantine from your GraalVM directory: sudo xattr -r -d com.apple.quarantine $GRAAL_HOME.

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. As of Occtober 2022, Tortoise has been updated to work with GraalVM version 22.2.0, Java 17 edition.

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.

Add a custom footer
Add a custom sidebar
Clone this wiki locally