1. Setting up your dev environment

We recommend VSCode for developers of Nimble, and developing inside a Docker container. You're free to use other tools, but then you're on your own to get all your dependencies set up. We also recommend developing on a Linux machine (instead of a Mac) for faster build times.

Prerequisites

First off, you need to ensure you have two pieces of software installed:

• VSCode - An amazing, free, and open source IDE by Microsoft
• Docker - A lightweight alternative to VMs (ish)
  • We recommend installing Docker Engine.
  • You can run docker run hello-world in your terminal to see if you have docker already installed.

Once you've downloaded VSCode and Docker, you'll need to open up VSCode and install the "Remote - Containers" extension for VSCode (hover over the icons on the left sidebar until you see "Extensions", then search and install the extension). You can read more here if you're interested, though it shouldn't be necessary.

Once that's installed, if you're on a Mac you'll need to start the Docker Mac app, in order to host the linux VM that will run your Docker instances.

Open the repository in a docker container

Now open up the nimblephysics folder in VSCode. You may see a notification in the bottom right that says "Folder contains a Dev Container configuration file. Reopen folder to develop in a container (learn more)." If you do, you can simply click the "Reopen in container" button. If you don't see that, you manually boot into the container with the following:

• Hit shift+ctrl+p to open a command window in VSCode (shift+cmd+p on Mac)
• You're looking for "Remote-Containers: Open folder in container..." so type as much as you need in order to get that to come up, and then click on it (or press enter)
• This will open a folder dialog to pick which folder to open in the container. Just select the root of the nimblephysics repo.

It make take a few minutes while VSCode downloads, builds, and boots your Docker container locally. Once it's done, VSCode will automatically connect you into the Docker host and the screen will refresh and you'll have a self-contained development environment running in CentOS 7, with all the dependencies and tools pre-installed for you. Why CentOS 7? Because that's what PyPI requires we build our deployed code in in order to be compatible with as many linux distros as possible when people pip install nimblephysics. Since that's what our CI system uses, that's the development environment too to avoid confusion and pain.

You can verify whether your docker container is running with the command:

$ docker container ls
CONTAINER ID   IMAGE                                                COMMAND                  CREATED         STATUS         PORTS                          NAMES
839712b429ce   vsc-nimblephysics-f5cbf187e13365d96b7d922f78d67b0d   "/bin/sh -c 'echo Co…"   6 minutes ago   Up 6 minutes   8070/tcp, 8080/tcp, 9000/tcp   eager_mirzakhani

You should an output that looks something like the example output above. The specific IDs will be different, but your image should say something like nimblephysics in its name.

Troubleshooting

If the dependencies have changed since you last built the container, you might need to rebuild the container (especially if you're getting dependency-related build errors). You can try either of the following through the VSCode command palette:

1. "Remote-Containers: Rebuild Container"
2. "Remote-Containers: Rebuild Container Without Cache"

If you get the message like the following (e.g. in VSCode):

Current user does not have permission to run `docker`. Try adding the user to the `docker` group.

See https://docs.docker.com/engine/install/linux-postinstall/.

If you're new to VSCode

Here are some quick tips:

• ctrl+p brings up a search bar you can use to quickly find files
• shift+f5 runs whatever target you've currently got set in the CMake plugin (see the next wiki page for how to do that)