Overview

This document will walk through what I have found to be the best way to build SUMO as well as contributing to the project. In general, the workflow looks like:

1. Fork
   1. Max has already forked to
2. Clone the to your local computer
   1. Good practice to always check the upstream branch () for commits that might impact what you are working on, as it is under active development
      1. If a change has been made, merge the upstream branch into your development branch and continue
3. Create a branch for your development & switch to that branch
4. Build SUMO in it’s entirety once
5. Development Loop
   1. Make changes to SUMO’s internals
   2. Build (just or )
   3. Test
6. Ready for contribution?
   2. Create a pull request on Github

Detailed Instructions

Cloning the Repository

Cloning the repository should be the same on all platforms. If you haven’t used Github since August of 2021, you may have to create a personal access token. This answer walks you through the process concisely.

Then, assuming that you are using the SUMO branch, you would clone it using

or if you setup an SSH key:

Prepping the Repository up for Development

First, make sure that your is setup properly, so that you can contribute to SUMO if the time comes. See .

You should then create a branch to track your development

If you want to add the ability to track and merge SUMO’s main repository:

Then, if you ever want to merge into your development branch:

Prepping VSCode for Development (on Windows)

I have tried both and and come to the conclusion that VSCode (with add-ons) is the better IDE.

Installing the Extensions & Necessary C++ Build Tools

The first step will be adding the necessary VSCode extensions, which the should cover.

I like to use package managers (homebrew on MacOS and apt-get on Linux), so I installed on Windows. You can install Chocolatey by following the .

Once is installed, you can install with (Make sure that you are inside of an administrative shell)

Installing Necessary C++ Libraries

SUMO provides a bundle of necessary C++ Libraries for Windows development. You can clone the libraries from . You should clone the library in the folder per their instructions.

I found that I also need to set the environmental variable. If that is the case for you, I would suggest cloning the repository outside of folder - as it will make more complicated.

You will likely have to close and re-open VSCode if you set the environmental variables.

Configuring CMAKE

After installing the extensions and libraries. Open the folder in VSCode. The following notification should pop up in the bottom right corner:

Select “Yes” to have CMAKE configure the project according to

Once the configuration finishes, the bottom bar should look something like below:

• The CMake button allows you to select the build variant.
  • I have not strayed from
• The Active Kit Button is for choosing the CMake Kit
  • On UNIX, this is clang or gcc
  • On Windows, this is Visual Studio Community 2019 Releases
    • You have to have the installed
• The bracketed [ALL_BUILD] button allows you to select the program to build.
  • This allows you to build only the executable that you want to debug.
  • Initially I would recommend building all the sources, and then switching to just [sumo-gui] of [sumo] which saves compile time while debugging.

Building SUMO

Its possible that your selected build target from above already built. If not, click on the ⚙️ Build button and CMake will start building the target.

• You should first build all of the sources and then change to just or
• ==Reach out to Max if errors occur during the build process==

Debugging SUMO

Debugging in VSCode is reliant on the file. To create it, go to the “Run and Debug” tab on the left sidebar and select create a launch.json file. The auto-configuration doesn’t matter as you are going to copy the file below.

The following should be a working example of a file that runs the NEMA test files from SUMO. It is platform specific, so if you are on something other than Window, reach out to Max.

The launch task configured in does a couple of things automatically:

1. It builds the target specified in the bottom tool bar ([sumo-gui])
2. It changes the directory of the subsequent task to what’s specified in
3. It launches the built target with the arguments specified in in an external terminal
4. It attaches a debugger to target

Attaching to an Existing SUMO Instance

If you are following along in Single Intersection Airport Harper, you were probably routed here.

To debug a “running” simulation, we need to attach to the process. The following addition to the will allow us to do just that

Then run the “(cppvsdbg) Attach” in the debug window and it should open a dialog box for you to search for the process ID. Just simply search “sumo” and you should find the process. This will attach the debugger and you can step through the simulation!

Running a Simulation with the Debugger

Because this document was created to help extend NEMA dual ring controller, we will start by debugging its entry point: .

The bulk of the logic occurs inside the function.

You can place a break point on any line in this code and start debugging.

provides a graphical view of the NEMALogic function.

More will be added to this document as necessary…