Contributor Guide

NOTE: This page was migrated from the old README and could benefit from more detailed notes. Edits are welcome!

Introduction

This page includes instructions for developers who are looking to build SDEverywhere and contribute to the project.

If you are a user of SDEverywhere, you can safely ignore this page. For more user-focused documentation, consult the top-level wiki and README pages for this project.

Dependencies

Requirements

You can build SDEverywhere and contribute to its development on macOS, Windows, or Linux.

Developing SDEverywhere on macOS requires the free Xcode development tools from Apple.

Install Node.js

Install Node.js version 14 or later. This will also install the npm Node Package Manager.

Clone the repos

Clone the SDEverywhere and antlr4-vensim repos in a project directory of your choice using either git on the command line or Sourcetree (see below).

If you are using command-line Git, clone each repo and track the main branch, substituting your project directory name for "{project directory}".

cd {project directory}
git clone https://github.com/climateinteractive/antlr4-vensim
cd antlr4-vensim
cd ..
git clone https://github.com/climateinteractive/SDEverywhere
cd SDEverywhere

If you are using Sourcetree, do File > New > Clone from URL. Fill in the form as follows, substituting your project directory name for "{project directory}".

Prompt	Contents
Source URL	https://github.com/climateinteractive/antlr4-vensim.git
Destination Path	{project directory}/antlr4-vensim
Name	antlr4-vensim

Then do the same for SDEverywhere.

Prompt	Contents
Source URL	https://github.com/climateinteractive/SDEverywhere.git
Destination Path	{project directory}/SDEverywhere
Name	SDEverywhere

Track the main branch for both repos in Sourcetree by opening "origin" under Remotes in the sidebar, and then double-clicking main. Click the Checkout button.

When running SDEverywhere in development, you can also link the local version of antlr4-vensim by adding the following to package.json:

{
  "pnpm": {
    "overrides": {
      "antlr4-vensim": "link:../antlr4-vensim"
    }
  }
}

Then run pnpm install.

If you need to run SDEverywhere in a debugger, use the instructions in the Debugging Tips page.

Test your setup

If you cloned the GitHub repo, you can test your installation by building and running the models in the models directory, and then comparing SDEverywhere output to Vensim output. Each model has its own directory under models with the same name as the model.

Before running the tests for the first time, it is necessary to build all packages in the repo (primarily because the compile and cli packages depend on the build package):

pnpm build

To run all model tests:

pnpm test:c-int

Contributing a change

If you find a bug in one of the SDEverywhere packages, or want to propose a new feature, please check for an existing issue, and if none found, file a new issue.

Pull requests are very much welcome!

If you have the time and ability to propose a fix or new feature:

1. Create a fork of the SDEverywhere repo.
2. Create a test case that fails (without your fix).
3. Implement your fixes/feature.
4. Verify that your test case and all other tests are passing (pnpm test).
5. Once you are satisfied with your changes, create a pull request.

All bug fixes and new features must be accompanied by an automated test that verifies your changes, i.e., one or more of the following:

• a Vensim / C-level "model test" (example, also refer to Sample Models page)
• a JS-level unit test (example)
• a JS-level integration test (example)

If you need help preparing a test case, please get in touch on the discussion board.