-
Notifications
You must be signed in to change notification settings - Fork 189
Tooling
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.
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 .
The build system integrates well with Clang tools:
cmake .. -DWITH_CLANG_TIDY=ONcmake .. -DCMAKE_CXX_INCLUDE_WHAT_YOU_USE="iwyu;-Xiwyu;--no_fwd_decls;-Xiwyu;--max_line_length=120;-Xiwyu;--keep=config.hpp"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_testsMake 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.txtThe 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}}"The project uses autopep8, ClangFormat and cmake-format for code formatting and pylint for linting. Their execution is managed by pre-commit.
We recommend that contributors install the necessary dependencies and run the linter and formatters before opening a PR. The Python dependencies are listed at the end of requirements.txt and can be installed locally using the syntax shown below, where X.Y.Z are the respective package versions, which are updated every 2 years and are based on the versions available in the Ubuntu LTS. The quotes are mandatory for packages with the greater-than symbol to avoid redirection to a file.
pip3 install --user 'autopep8==X.Y.Z' 'pycodestyle==X.Y.Z' 'pylint>=X.Y.Z' ...Here are a few commands to get you started with pre-commit:
# help page
pre-commit run --help
# run on all files modified since the last commit in upstream
pre-commit run --files $(git diff --name-only upstream/python)
# run on all files
pre-commit run --all-files
# run on all files, except pylint and autopep8
SKIP=pylint,autopep8 pre-commit run --all-filesTo avoid typing pre-commit commands every time, the tool can be configured with git hooks to automate the linting and formatting actions during certain git events, such as commits. This behavior can be temporarily disabled with SKIP=pylint,autopep8 git commit -m "message". Please refer to the pre-commit manual for how to set up git hooks in your ESPResSo fork.
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 "[email protected]"
git config --global user.name "John Doe"
git config --global push.default simpleUse 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.
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 [email protected]:username/espresso.git
cd espresso
git remote add upstream [email protected]:espressomd/espresso.gitAt this stage, git remote -v should display the following:
origin [email protected]:username/espresso.git (fetch)
origin [email protected]:username/espresso.git (push)
upstream [email protected]:espressomd/espresso.git (fetch)
upstream [email protected]:espressomd/espresso.git (push)The remote origin refers to your fork, while upstream refers to the main ESPResSo repository.
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-443You can now open a PR on the main ESPResSo repository.
For more details, please refer to Collaborating with issues and pull requests.
You can reproduce the build environment used in our CI pipeline using Docker. The Docker images are available on GitHub and DockerHub (under espressomd). They can also be built locally: the Docker image tag contains the commit SHA and name of the corresponding Dockerfile in espressomd/docker.
The exact ESPResSo build and test sequence can be 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.shPlease note the Docker image tag is subject to change! We update these Dockerfiles every 4 months on average.
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)
- 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"
- 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
- 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)
- 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