BALL Hacking Guide

BALL is a huge library, that has its own rules, tricks, quirks, and oddities. This page tries to give some pointers on how to add new features into BALL.

Directory Structure

First let us take a look at the BALL directory structure:

• BALL/
• contrib/ Contains the contents of the contrib package. Just ignore it.
• cmake/ Contains macros for the buildsystem.
• data/ This contains the data files that are shiped with BALL: Atom radii, charges, rotamer libraries, force field configurations. In general everything that is not a source file but is needed by some class of BALL can be found here.
• source/ Contains all implementation files. Your own implementation goes into the appropriate subdirectory here.
• APPLICATIONS/ Contains some applications built on top of the BALL libraries, most notably BALLView.
• VIEW/ Everything that has to do with visualization goes in here. The files in this directory are compiled into the VIEW library.
• PYTHON/ This contains the Python bindings. When you are done with your own C++ class, you should add bindings to it here.
• others/ All other directories are compiled into the BALL library. The names should be pretty self explanatory.
• include/
• BALL/ Contains all header files. Your headers go into the appropriate subdirectory here. The folder structure is the same as the one of the source folder.
• doc/ Contains the documentation of BALL. There is a doxygen.cfg file that you can use to generate an up-to-date API documentation.
• Windows/
• MacOSX/ The last three directories contain additional files needed for the deployment on other platforms. You most likely do not need to touch them.

Source Files

There are several types of source files you will encounter when browsing through the BALL source code. As some might be quite confusing a short explanation can be found here:

• .C Boring standard C++ source files. Some of them are empty. This is because the class they belong to is a template class that is completely defined in headers.
• .h Header files. Not much to see here.
• .iC C++ source files containing template implementations. This is the reason why they are found in the include/ directory.
• .l Input files for the Flex lexer generator.
• .y Input files for the Bison parser generator.
• .sip Input files for the sip Python binding generator.
• .ui Definitions of GUI elements for the Qt UIC compiler.

Before you start

All right, you are eager to get coding. But before you do so take a look at the CodingStyle and think about how you are going to organise your work. At least you should work in your very own git branch. There you can modify your code and commit changes without changing the main repository. (This is also true for the master branch, however you most likely will run into trouble when your changes are commited into the main repository). You create a branch with the command

git checkout -b some_fancy_name

In this branch you can go rampage. Once you have made changes that are worth to commit just select the files containing the changes via

git add file.a file.b ...

and commit them with

git commit

When making commits please please please follow the following rules:

• Write descriptive commit messages. If your changes make it into the master branch your fellow developers will be most pleased if they can tell what a certain commit did from simply reading the commit message. Ideally a commit message should look like this:

Fix bug in Foo::bar()

In bar() the call to bla() caused a bug in the flux compensator. 
Work around this by first recalibrating the dilithium matrix prior to calling bla().

The empty line above tells git to take the first line as a short description for the commit.

• Feel free to add humorous or poetic commit messages, but do not insult other developers (even if they earn it) and do not forget to include information about what this commit does. Showing everybody that you are a second Shakespear does not earn you anything.
• Try to make atomic commits. This means: every change that works independently of other changes should get its own commit. This makes it easier for maintainers to manage the source code and helps to keep the development history clean.
• Test before you commit. This is not always possible, but you should make sure that your code at least compiles and ideally does what is on the tin (namely the commit message).
• Every time you do not obey one of the above rules a cute kitten dies! So please take the time to stick to the rules and save a kitten's life ;-)

The Build System

Since version 1.3.1 BALL ships with a CMake based buildsystem which not also speeds up the compile process considerably but also is easier to maintain.

Adding New Files

You added a new class, lets say FooBar, to BALL. It is located under BALL/source/STRUCTURE and the header resides in BALL/include/BALL/STRUCTURE. First the BALL Buildsystem needs to be told that the file actually exists. For this open the sources.cmake in the source/STRUCTURE directory and add your source file (in our case fooBar.C) to the CPP_SOURCES variable.

Afterwards it should look like this:

...
SET(SOURCES_LIST
    many.C
    other.C
    files.C
    fooBar.C
...
)

Afterwards try to rebuild BALL by issuing make. This should build your new class and link the new library.

Adding New Directories

Adding new directories requires a little bit of more work. First we need to tell the buildsystem that the directory exists. This again depends on where you are placed in the directory tree.

• source/your_dir: Open the file cmake/BALLIncludes.cmake and add a pair of include statements for your directory:

INCLUDE(source/your_dir/sources.cmake)
INCLUDE(include/BALL/your_dir/sources.cmake)

and add your directory there. Of course you also have to add the respective sources.cmake files. Just copy them from another directory and modify them accordingly.

• source/some_dir/your_dir: Open the two sources.cmake of the directory containing yours (both in the include and source tree) and include your subdirectory there.