Overview

Here's how to build NetLogo release bundles.

Some of this information is usable by anyone. Some of it only applies to developers at Northwestern doing official CCL-sanctioned releases.

As you work through these instructions, look for things which could be more fully automated and automate them!

"Easy Mode" Linux builds

If you only care about obtaining a Linux build, you can do skip all of this other stuff and get one pretty easily by following the instructions here.

Prerequisites

Overview

The release build process is currently split into three steps:

1. A full build of NetLogo and various components that must each be done in the target OS
2. OS-specific packager generation which must be done on the target OS
3. The NetLogo page generator and uploader, which can be done on any OS

General dependencies

• jpackage: included with the JDK.
• npm: must be in your path. Used to build the PDF version of the NetLogo manual.
• python3 and numpy: Python must be in your path, and numpy must be installed with pip. Needed for the python extension test.
• aspell : must be in your path. Needed for documentation spellchecking. On MacOS can brew install aspell in a terminal window if you have Homebrew.
• ImageMagick: must be in your path (command is called magick). Required for banner image creation on all platforms, as well as app icon creation on Windows and Mac. Installation information.
• create-dmg: required for installer creation on Mac. Can be installed with homebrew or from the GitHub page.
• yarn: required for building the docs and user manual PDF. Installation information.

Setting up JDKs

The pre-2025/NL7 release system tried to do all sorts of "clever" sorcery, in a vain attempt to automatically find JDKs based on the operating system. For NetLogo 7, that was discarded and replaced with build-makers just explicitly stating the JDKs that they want to use for their build, as described in their .jdks.yaml file in the root of the repository.

The format of a JDK entry in the file will look something like this:

- vendor:       "OpenJDK"
  version:      "17.0.2"
  architecture: "64"
  path:         "/my/favorite/jdk-store/jdk-17.0.2/"

Valid values for architecture are "32" or "64" for Windows and Linux, and "x86_64" or "aarch64" for Mac.

The path should be the value that you would otherwise use for a JAVA_HOME value, such that the expected executables are all present relative to path (e.g. bin/java, bin/javac, bin/jpackage (and with .exe at the ends of the names of those executables, on Windows)).

Pre-release tasks

For the list of things that you should update, check, and verify before making an official release, see this page.

Release notes

As a developer, you're not responsible for writing the release notes, but you need to make a change log that will serve as the skeleton for the release notes, and get that change log approved by The Powers That Be, and then into the versions.md.mustache file.

Before embarking on this quest, check out the relevant milestone on GitHub. Re-assign any remaining issues, and close the milestone.

Then, there are many strategies that can be used for building the change log. One is the bin/issues.scala script, but that requires that everything in GitHub be mega-well-organized. It's not very realistic. Another is the private wiki, where you can accumulate release notes as you go along, but that requires constantly updating that document. What's more, everything needs to end up in Google Docs eventually, anyway, so that it's accessible to The Powers That Be, so using the internal wiki isn't advisable, either.

Here's Jason's preferred strategy: When you're about ready to build, just read through the Git log since the tag of the last release. It won't be fun or quick, but it will be accurate. Also, make sure to check the Git logs of the submodules (e.g. Models Library, extensions, Mathematica Link, BehaviorSearch). You can probably get the Model Czar to supply you with a summary of the changes to the Models Library.

Also, make sure that you note any known regressions for inclusion in the release notes. If stuff that people would ordinarily expect to work is broken, we typically remind them about it in every release.

Once you have a change log assembled, get it into a Google Doc that's shared with The Powers That Be.

After they eventually give you a finalized version of the release notes, copy the change log from that document and add it to docs/versions.md.mustache.

Building

Overview of commands

Once your JDK has been entered into .jdks.yaml, you just need to run a few commands.

• dist/buildNetLogo will do the actual build
• dist/package<platform>Aggregate <jdk> will bundle up the relevant files for distributing to the public, and drop them into dist/target/downloadPages
  • <platform> will be Win, Mac, or Linux depending on which platform you're building for at the moment (likely constrained by which operating system is running on the machine that you're running this command on)
  • <jdk> is the name of a JDK, as computed from the information describing it in .jdks.yaml
    • For example, the JDK described in the example above would go by the name OpenJDK_17.0.2_64
    • You can simply press Tab to get a list of valid options, as pulled from .jdks.yaml

Building

Once all the desired changes are in, and the release notes have been finalized, it's time to build.

How to build on...

• Windows
• macOS
• Linux
• Linux via Docker (AKA easy mode)

Testing

In order to be sure that the build is good, perform the "smoke tests" described on the Release Testing page.

Deploying

Tagging

Tag the release in Git—even release candidates:

git tag v<version number>
git push origin main --tags # root being your current branch

Uploading artifacts to Cloudsmith

Ensure that your copy of the repo is pointing to the tagged commit. Then, in SBT, run

publishVersioned headless
publishVersioned netlogo

and, if the parser version number increased, because of changes to the parser, also run:

publishVersioned parserJS
publishVersioned parserJVM

Note that the Cloudsmith GUI allows you to delete unwanted uploads, if necessary.

Staging to the NetLogo site

(These instructions might be obsolete, since we'll soon be hosting files in a better place. How to do that will be added in a future update to this page.)

Set aside some time for this step. I've seen this take ~7 minutes; I've seen it take ~40 minutes.

• If multiple people have built installers do the following:
  • Before doing the build, clear out the residue from any past deploy by running rm -rf target/downloadPages/ dist/target/downloadPages/ dist/target/<release_name>
  • Once all builds are completed, get the six of them into your possession (Linux 32, Linux 64, Windows 32, Windows 64, Mac Intel, Mac Silicon) (possibly from a shared folder on Dropbox or Drive or something), ultimately placing them all into dist/target/downloadPages
  • If you're the sort of cool guy who runs his builds inside a Docker container, you won't have the docs generated outside of the container, so generate them with the allDocs command in SBT, or you can set up your test build and take the NetLogo User Manual.pdf and docs/ files from the root of the installed build, and copy them into netlogo-gui.
  • Before too long here, we'll be uploading the builds to the CCL server. The uploadWebsite task in project/NetLogoPackaging.scala is of the persuasion that your username on the CCL server will be the same as your username on the machine that you're uploading from—a bad assumption. Instead, make sure that your CCL server user name gets into the user variable in that task somehow. Run reload in SBT (or open it anew), if you made any changes to NetLogoPackaging.scala.
  • Then, in sbt run the following:
    • dist/generateLocalWebsite
    • dist/buildDownloadPages
      • Feel free to pause here and check dist/target/downloadPages/index.html, to ensure that the date and size of the downloads seem correct
    • dist/uploadWebsite
  • Finally, ensure that you can download at least one of the installers
    • Some claim that there are "usually" permissions issues with files uploaded to the server, but Jason has never had an issue with it. If you feel like you've run into permissions issues, try to remedy the problem with these commands:
      • ssh ccl.northwestern.edu chmod -R go+rX /usr/local/www/netlogo/<version>
      • ssh ccl.northwestern.edu chgrp -R apache /usr/local/www/netlogo/<version>

Next, we'll SSH into the server and get everything set up, without making it show up on the main download page (download.shtml).

The folder setup on the NetLogo website uses a series of symbolic links to try to keep URL updates to a minimum. It kind-of works. For example, the docs link points to the latest minor version, so docs -> ./6.1/docs, but the minor version is just a symlink to the latest patch version, so really docs -> ./6.1/docs -> ./6.1.1/docs.

• Pull down the latest version of the netlogo-site repository.
• Create the placeholder dirs: mkdir 6.1.1; mkdir 6.1.1/docs; mkdir 6.1.1/models
• If you're doing a patch version update (6.1.0 to 6.1.1):
  • rm 6.1 # remove old minor-version symbolic link that was pointing to 6.1.0 -- check first
  • ln -s 6.1.1 6.1
• If you're doing a major or minor version update (say, 6.1 to 6.2):
  • rm docs; rm models/models
  • ln -s 6.2/docs docs; cd models; ln -s ../6.2/models models
• You can then search (via grep -R or git grep or your text editor's search) for files containing the old version you are replacing.
  • However, don't blindly delete occurrences of the previous version number; some (such as in oldversions.html) are to coexist with the new version number.
• Commit all your changes (including the symlink changes) and push them up to the server on a branch. Here is an example of some updates for a patch-version release. Here is an example of some updates for a minor version release.
• Once everything looks good, merge to master and push again (or merge via pull request)
• Once the GitHub Actions deploy of the netlogo-site is done (you can kick it off early if you're impatient), everything should be updated on the server.
• Browse the site and make sure the download links and documentation links are all correct.
• Make sure the Models Library and Community Models pages are correct.

Staging elsewhere

Then, since we're transitioning away from having docs on the CCL site, you need to add them to the Docs repo.

• Add a folder to the root of the Docs repo, named after the new NetLogo version
• Drop the contents of netlogo-gui/docs into said folder
• Drop the user manual PDF into said folder
• Push to main
• Verify that it deploys to docs.netlogo.org/<version_number>

Then, get it staged in Directus

• Note the netlogo_versions bin
• Go into the download_urls bin that's a child of it
• Make copies of the existing downloads, but pointing to the URLs where the installers are actually being hosted
• Don't deploy them yet or hook them up to any entry in netlogo_versions; we'll do that when we're ready to make it public

Also, a release should be accompanied by an in-app announcement to let users know about it. Draft an announcement (possibly in coordination with others), log in to the Directus-based CRM, and add it to the list of announcements.

Share a download link with everyone who want to have test it.

And then wait until The Powers That Be are ready to send out the public release announcement.

Making it public

Once we're ready to announce it, we need to make everything public. To do that:

• Push any pending updates for the the Extension Manager listing
• Docs (example, other instructions)
  • Update the latest symlink
  • Add the new version to the versions.json file
• CCL Site: List it in the "versions" dropdown on download.shtml (example)
• Directus
  • Add a new version in the netlogo_versions bin
  • Connect it to all of the download_urls entries that you pre-staged
  • Delete the previous version from netlogo_versions
  • Delete all of the download_urls entries that were connected to the old version
  • Deploy it from here
• GitHub: Upload the artifacts for the release here and mark it as the latest release
• Tell The Powers That Be that we're now live, and wait for them to announce it

Post-release cleanup

• Update Wikipedia with the latest version number and date (actual link)
  • Make sure to mark the latest release with the ⬆️ (preferred rank), and remove the preferred rank from the previous release
• Revert everything back to isSnapshot := true
• Update wiki pages:
  • This page
  • Architecture
  • Devel requirements
  • Others