Skip to content

Tooling

Jump to bottom
Jean-Noël Grad edited this page Aug 23, 2021 · 10 revisions

This page assumes that you have set up a working build environment for ESPResSo. Instructions can be found in the Installation section of the User Guide.

The following sections will explain how to set up a development environment for ESPResSo. If you encounter any issue, please refer to the Installation FAQ.

Table of Contents

Build system tooling

You will need a recent version of CMake to compile the code. If your version of CMake is too old, you can install a newer one with the pip package manager: 

pip3 install --user 'cmake==3.17'

The build time can be reduced by using ccache. This can be enabled by the CMake option WITH_CCACHE, e.g. 

cmake -DWITH_CCACHE=ON .
in the build directory. This requires the ccache binary to be available.


The build system integrates well with Clang tools:

clang-tidy: 

cmake .. -DWITH_CLANG_TIDY=ON

include-what-you-use: 

cmake .. -DCMAKE_CXX_INCLUDE_WHAT_YOU_USE="iwyu;-Xiwyu;--no_fwd_decls;-Xiwyu;--max_line_length=120;-Xiwyu;--keep=config.hpp"

scan-build: 

scan-build cmake .. -DCMAKE_BUILD_TYPE=Debug -DWITH_CUDA=OFF -DWITH_PYTHON=OFF
scan-build -k -o static-analysis/ make -j$(nproc)
scan-build -k -o static-analysis/ make -j$(nproc) check_unit_tests

Python packages

Make sure all dependencies listed in requirements.txt are installed on your machine. This can be achieved with the following command: 

pip3 install --user -r requirements.txt

The pip package manager will always install the newest version of a package, unless a version that meets the requirements is found. You can pin a package version like so: 

pip3 install --user 'scipy==1.6.0'

Some of these dependencies will install binaries, e.g. sphinx, and jupyter and autopep. These binaries need to be accessible in your terminal. This is achieved by setting the $PATH environment variable. This variable can be set automatically by editing your ~/.bashrc and adding the following line: 

export PATH="${HOME}/.local/bin/:${HOME}/bin${PATH:+:${PATH}}"
This shell command adds ~/.local/bin: in front of the $PATH variable. If the variable was an empty string, it will set it to ~/.local/bin. The colon symbol acts as a separator between paths.

Git

Profile setup

Set up your GitHub profile with a verified email address, and with an authentication method to be able to push your changes from the command line, for example via SSH (see Connecting to GitHub with SSH).

Set up your git profile with the information from your GitHub profile: 

# set username/email globally (remove --global to set locally in the .git folder)
git config --global user.email "john.doe@icp.uni-stuttgart.de"
git config --global user.name "John Doe"
git config --global push.default simple

Use the same user name and email address as the ones in your GitHub account if you want your commits to be attached to your GitHub account (they will appear in your statistics and be decorated with your profile picture). If the information doesn't match, a default grey icon will appear next to your commits instead of your profile picture.

Repository setup

Create a fork of the ESPResSo project on GitHub with the Fork button, then download the fork on your workstation and set the upstream branch with the following commands (assuming your GitHub login is username): 

git clone --recursive git@github.com:username/espresso.git
cd espresso
git remote add upstream git@github.com:espressomd/espresso.git

At this stage, git remote -v should display the following: 

origin	git@github.com:username/espresso.git (fetch)
origin	git@github.com:username/espresso.git (push)
upstream	git@github.com:espressomd/espresso.git (fetch)
upstream	git@github.com:espressomd/espresso.git (push)

The remote origin refers to your fork, while upstream refers to the main ESPResSo repository.

Publishing your work

Here is a typical workflow to commit changes locally and push them to the fork: 

# fetch the latest commit upstream
git fetch upstream python
# create a new branch to fix ticket #443
git checkout -b fix-443 upstream/python
# do the changes
sed -i '/cmake_policy(SET CMP0025 NEW)/d' CMakeLists.txt
# commit the changes
git add CMakeLists.txt
git commit -m 'CMake: Remove policy CMP0025'
# push the branch to the fork
git push -u origin fix-443

You can now open a PR on the main ESPResSo repository.

For more details, please refer to Collaborating with issues and pull requests.

Docker

You can reproduce the build environment used in our CI pipeline using Docker. The Docker images are available on GitHub and DockerHub. The image SHAs and environment variables are found in .gitlab-ci.yml. Here is how to pull an image locally and run the maxset CI job on Ubuntu 20.04: 

docker run --user espresso docker.pkg.github.com/espressomd/docker/ubuntu-20.04:1c6cfb03f7cedf008cf0d288fe460303627fc217 bash
git clone --depth=1 --recursive -b python https://github.com/espressomd/espresso.git
cd espresso
export with_ccache=true build_procs=$(nproc) check_procs=$(nproc)
export CC=gcc-9 CXX=g++-9 with_cuda=false myconfig=maxset with_coverage=false
export with_scafacos=true with_stokesian_dynamics=true
bash maintainer/CI/build_cmake.sh

IDE

VS Code

Visual Studio Code and its Live Share extension can be quite convenient for pair programming on C++ code. Both programmers need to use the same version of the IDE. It can be installed on Linux workstations without admin rights. Below is the installation and configuration procedure for version 1.59.

Installing VS code:

  • a .tar.gz archive can be downloaded from the official website (https://code.visualstudio.com)
  • run the executable (VSCode-linux-x64/bin/code on Linux)
Installing VS Code extensions:
  • Ctrl+Shift+X to open the Extensions panel
  • if not already installed, search in the Marketplace and install "C/C++", "CMake", "CMake Tools", "Live Share"
Configuring VS Code Live Share:
  • click on the Live Share icon (left panel of VS Code, the icon looks like an arrow above a circle)
  • you can now join sessions as an anonymous user
To create VS Code Live Share sessions, you need to log in using either a GitHub or a Microsoft account:
  • configure Live Share: click sign-in
  • with GitHub: select sign-in from GitHub, your browser will open a new tab
  • click approve in the GitHub page (when you get confirmation, do not close the tab yet)
  • if nothing happens in VS Code, go back to the GitHub page and click "Having trouble? Click here for user code directions" to get the token, and copy-paste it in VS Code
  • you should now be logged in (icon with your name in the bottom-left corner of the VS Code interface)
To run python scripts with pypresso:
  • install the "Python" extension
  • click the gear at the bottom left and choose Settings
  • search for "Default Interpreter Path"
  • update the field with the absolute path to the pypresso executable in the build directory
Clone this wiki locally