Building - NetLogo/NetLogo GitHub Wiki

To hack on NetLogo, you'll need to know the following.

You will need a Git client, the sbt build tool, and a JDK 17 install.

The sbt tool handles getting the correct versions of itself as well as the Scala compiler and libraries needed by NetLogo.

We use Liberica OpenJDK 17 for developing, testing, and releasing NetLogo, so it is officially supported. The Oracle JDK releases should continue to work as well. Other OpenJDK 17 bundles should also work but not all of them include the OpenJFX package and the jpackager tool, which NetLogo's packaging process depends on.

That should be enough for basic hacking and running tests, but if you want to do a full release build you'll need a few more dependencies; see the Releasing page for info on that.

git clone https://github.com/NetLogo/NetLogo.git
cd NetLogo
git submodule update --init
./sbt netlogo/run

If this works, it will download stuff and build jars and other build products. If it fails with a bunch of errors about missing extensions and/or models, you probably forgot to do git submodule update --init.

You can also just run ./sbt to start an interactive sbt session, which is preferrable when making changes so you can compile and run tests.

The major branch is hexy.

For details on all our development branches, see Branches.

Windows sbt support is available for NetLogo 6.0 and later. See our detailed Windows Setup instructions for configuring a Windows development environment.

On an Apple computer, macOS 10.8 or later is required. You must install Xcode, a free download from Apple through the App Store. Once Xcode is installed, you must also run Xcode and install the optional Command Line Tools component.

The ./sbt script you use to run sbt with the NetLogo repo will run /usr/libexec/java_home -F -v17 in order to find the correct version of Java 17 on macOS. If you run that command and nothing turns up, or the incorrect install turns up, you'll either have to make sure to get the correct JDK installed, or you'll have to modify the ./sbt shell script to run with your version of Java.

Some extension builds may also require curl, which might not be installed by default (on Ubuntu, you can sudo apt-get install curl; on Mac OS X, the same if you use Fink, or brew install curl if you use Homebrew).

If you have a JDK that does not include OpenJFX, it can be installed on most Linux systems using snaps OpenJDK

The following are needed to build hexy in Ubuntu:

• git
• java (and friends) installed with update-alternatives
• curl
• pandoc
• nodejs (if building parserJS for tortoise)

To build NetLogo in Fedora install OpenJFX if your JDK does not include it.

To build NetLogo in openSUSE:

1. openjfx is not included in the official repository, you may need to install it.
2. Try ping $HOSTNAME. If there are errors, then you can do the following: get your hostname by echo $HOSTNAME, add 127.0.0.2 your-host-name to /etc/hosts, you may also need to add your-host-name to the right of ::1.
3. Admin right is needed to run update-alternatives --display in NetLogo code. A quick fix to this is to modify all update-alternatives to sudo update-alternatives manually. To know where you need to modify, you can run grep -r update-alternatives at the root directory of NetLogo.

To build Netlogo in Arch Linux and its derivatives:

Install the following packages:

1. dpkg
2. jdk17-openjdk
3. java17-openjfx

You will get the following output when you run ./sbt

./sbt

WARNING: A terminally deprecated method in java.lang.System has been called
WARNING: System::setSecurityManager has been called by sbt.TrapExit$ (file:/Users/aab1638/.sbt/boot/scala-2.12.10/org.scala-sbt/sbt/1.3.13/run_2.12-1.3.13.jar)
WARNING: Please consider reporting this to the maintainers of sbt.TrapExit$
WARNING: System::setSecurityManager will be removed in a future release
[info] welcome to sbt 1.3.13 (BellSoft Java 17.0.4)
[info] loading settings for project netlogo-build from plugins.sbt,build.sbt ...
[info] loading project definition from /Users/aab1638/NetLogo/project
[info] loading settings for project root from classycle.sbt,build.sbt ...
[info] loading settings for project behaviorsearchProject from build.sbt ...
[info] set current project to root (in build file:/Users/aab1638/NetLogo/)
[info] sbt server started at local:///Users/aab1638/.sbt/1.0/server/082ea6d6e6846d81f455/sock
sbt:root>

You can compile, run, etc. from this shell. Type in 'help' or refer to About the build for more info.

Our main build tool is SBT (Scala Build Tool) version 1.x. SBT itself is written in Scala and is popular in the Scala community. SBT build files are themselves written in Scala (in build.sbt and project/*.scala).

You should run git submodule update --init and ./sbt all once to get started. Running ./nightly.sh (or ./nightly.sh --clean) runs ./sbt all and also runs our automated tests.

After having run ./sbt all once, often you can just work in SBT. ./sbt to start it up, then test, test-fast, package (builds JARs), run, etc.

hexy has several projects. See the wiki page on Hexy build architecture. In sbt you can run a particular command on a particular project by prefixing the command with the name of the project and a slash. So compiling the netlogo project (on the hexy branch) becomes ./sbt netlogo/compile.

Some pieces of the full NetLogo package are kept in separate repositories, using git's submodules feature. The Models Library, as well as each bundled extension live in individual repos, to make it easier for extension developers to build and fork them individually. Each extension submodule should have a 5.x and a hexy branch, each of their respective HEADs tracked by the HEAD of the respective NetLogo branch.

SBT supports incremental building. Run ./sbt to enter the SBT shell, then issue commands like compile, which compiles the main tree. A table of some common tasks and the appropriate sbt command for each of them on each branch is below.

See the Tests page for more information on which tests to run.

Even if you setup an IDE with your project, you still need to run ./sbt all in order to do the initial build. No IDE files are checked into the source tree. If you use Eclipse, you may be able to use the sbteclipse plugin to generate an eclipse build configuration. If you use IntelliJ, you may be able use the sbt project import tool in IntelliJ (sbt plugin) to create a Project. Please note that both Eclipse and IntelliJ are likely to miss sbt tasks used to build the project. If you're just looking to build the project without the command line, you might also check out Lightbend Activator which wraps sbt in a nice web UI. Note that you will still need to provide Activator with the correct java home depending on which branch of NetLogo you check out.

Pro Git (Apress, available online) is a good intro book. The O'Reilly book is more in-depth, but works less well as a practical tutorial.

To use your IDE's remote debugger, add the following line to build.sbt at the end of the settings() section for whichever build you are debugging. At the time of writing, for netlogo-gui, that's line 180.

180     javaOptions += "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=localhost:5005"

when you next netlogo/run, you should see the following message:

[info] Listening for transport dt_socket at address: 5005

You can now tell your IDE to connect its debugger to port 5005 and start debugging. If you're using IntelliJ, you can follow their tutorial and if you're using VSCode's Java extension, you can create an "Attach" launch configuration.

This is only really recommended for Java portions of the codebase. Remote debugging works at the JVM level, so it does technically work for both Java and Scala code, but at least in IntelliJ, remote debugging of Scala is an exercise in frustration.

When not using a debugger, the following three calls are your best friends:

• println(...)
• throwable.printStackTrace()
• Thread.currentThread.dumpStack()

JVisualVM is also really useful. It comes with the Mac OS X Developer Tools; type jvisualvm to run it. It has a profiler and heap analyzer, can grab thread dumps, etc.

See Releasing for details.

See Build-Architecture-(hexy) for details. Each project contains src which in turns contains main and test. These folders contain the sources (Java & Scala combined) in packages (the org.nlogo. prefix is not reflected in the source tree). For example, FileDialog.java can be found in netlogo-gui/src/main/swing/FileDialog.java.

A few Java sources are automatically generated using JFlex, a lexer generator, or using custom Scala code. The input files for this are in project/build/autogen. The generated code is not kept in version control.

Version-controlled resources are in the resources directory. (Some internationalization-related resources are auto-generated and stored in target/resource_managed.)

The following directories are accessed when you run the application:

• netlogo-gui/docs -- User Manual in HTML. See #616
• models -- Models Library
• extensions -- submodules (see above) of the bundled extensions
• netlogo-gui/natives -- native libraries for those libraries that use JNI

These files and directories are not accessed by the application:

• build.sbt (file) and project (directory) -- SBT build
• dist -- files associated with distributing NetLogo to end users

Plus there are some extra files and directories at the root:

• bin, models/bin -- scripts used during development. most of them are written in Scala and run inside a shell script wrapper.
• target -- SBT puts build products here
• tmp -- some of our tests put temporary stuff here; bin/release.sh uses it too

• tc: runs org.nlogo.headless.TestCommands (to run one file do e.g. tc Generator)
• tr: runs org.nlogo.headless.TestReporters (to run one file do e.g. tr Lists)
• te: runs org.nlogo.headless.TestExtensions (to run just one file do e.g. te array)
• tm: runs org.nlogo.headless.TestModels (to run just one file do e.g. tm Fire)
• testOnly: runs a specific test given by a class name (e.g. testOnly org.nlogo.generator.TestHelperMethodSafe)
• depend: looks for dependencies between packages that aren't supposed to depend on each other; see Architecture for a list of what dependencies are and aren't allowed. included in nightly.sh
• pmd: run PMD to check Java source files for flawed/suspicious code
• bench: runs the engine benchmarks
• dump

this list isn't necessarily complete or up-to-date

There are also some scripts in the bin directory that do useful things.

• bin/shell.sh: does run-main org.nlogo.headless.Shell inside rlwrap, so you get a headless "command center" with GNU Readline niceness
• bin/benches.scala: repeatedly runs our entire benchmark suite. suitable for overnight runs. See Benchmarking
• bin/profile.scala: runs benchmark models under the HProf profiler, dumping results to tmp/profiles, suitable for viewing with PerfAnal

this list isn't necessarily complete or up-to-date

If building on Windows, you may see an error similar to the following:

[error] fatal: 'submodule' appears to be a git command, but we were not
[error] able to execute it. Maybe git-submodule is broken?

As part of building extensions, NetLogo tries to checkout all git submodules to make sure you have the latest of each extension before building. On Windows, this sometimes fails with the error above. When the Windows git installer (not cygwin git) is used and configured to have git work in the Windows command prompt, this error should not appear.