votca  1.5-dev
Developer and Contributor Guide

function/class summary

Reporting Bugs

To report a bug please create an issue on the appropriate github repo. Please be sure to provide as much information as possible such as:

Issues can be directed created on the appropriate github repo:

CPP Resources

A good starting point is to take a look at the cpp standard. Though the code has not always consistently followed the cpp standard we now make an effort to really enforce it and follow best practices.

CPP Tips

Here are a few general tips that should be followed:



Header Files



Naming in Classes

get/set Functions




Each repository contains a src folder. Within the src folder exists a library folder: libtools, libcsg etc... and a tools folder. A tests folder should also exist in the src folder. If it does not you should create one.

For every new object and algorithm created there should exist a test. We use the Boost libraries testing framework. Good documentation can be found here:

We will outline the general workflow here using the vec object in votca::tools. This object only has a header file it is in: tools/include/votca/tools/vec.h

Determine if a tests folder has already been created or not in /src if it has not take a look at what was done in the votca-tools repo.

  1. Create a test file in tools/src/tests/test_vec.cc must have the same name as what appears in the foreach in the CMakeLists.txt file. And place the following contents
#define BOOST_TEST_MODULE vec_test
#include <boost/test/unit_test.hpp>
#include <exception>
#include <votca/tools/vec.h>
using namespace std;
using namespace votca::tools;

Replace the '...' and ':' with the appropriate syntax. For more info on which boost test macros to use refer to the boost documentation

  1. To compile and test the code create a folder tools/build and run the following commands:
make test

Ensure you have an up to date version of cmake or use cmake3

Failed Travis Builds

There may come a time where one of the docker builds fails. It may be the case that the error message is clear and it can be reproduced on your host os. However, in the case that the error is specific to the enviorment used in the build the local enviornment can be simulated using a docker container.

Before you can use this approach docker must be installed on your host OS. Begin by running a docker image the default is:

docker run -it votca/buildenv:fedora /bin/bash

This will run an interative docker container which you can interact with in bash . The next commands will need to be adjusted to whatever local environment you need to reproduce to test the error in the travis build.

CPP Codeing Style Guide

VOTCA uses the clang formatter to automatically ensure consistent style. The style follows the google style fomatting rules. Have a look at .clang-format file in the main votca repository for details.

To run the clang-format function on file.cc

clang-format -i -style=file file.cc

'-i' ensures it will make change to file.cc, omitting the '-i' will display the changes without implementing them. '-style=file' ensures the format is read from the .clang-format file otherwise it will use a default style guide.

By default tabs should not be used to indent, avoid inserting '', it is preferable that spaces be used instead.

CPP Comment Guide

It is preferential that the following guidelines be followed when adding comments to code:

  1. The /* */ comment blocks should be avoided and the // used in their place. This is so that the /* */ comment blocks can be easily used for debugging.
  2. It would be preferential that the following doxygen commenting stencil be used in the header files above each class and function description.
** Detailed function/class description if needed
* @param [in] - description of parameter 1
* @param [out] - description of parameter 2
* @param [in,out] - description of parameter 3
* :
* @return - description of return type

The doxygen commenting will help future developers maintain the code, in its fully compiled state it may be found at: http://doc.votca.org

NOTE: Compilation of the doxygen documentation is automated when code is merged into the master votca branch!

Updating Git Submodules

Votca with all of its repos can be build by using the parent votca repo. All the other necessary repos appear as submodules in the parent repo. It is worth noting that the submodules are not automatically updated whenever changes are made to their respective master branches. In essence a submodule refers to a specific commit of the repo it represents. If a new commit is merged into the master branch of a repository the submodule state in the parent repo has to be updated for the commit to propagate to the parent votca repository.

To update the state of a submodule the following commands can be used:

git submodule foreach git checkout master
git submodule foreach git pull
git add -u
git commit -m "update all submodules"