BALL Development Environment

Note: As of version 1.3.1 BALL features a CMake based build system. For building older versions under a Unix like system refer to DevelopmentEnvironmentAutotools.

There are various ways to set up a Development Environment. BALL runs under Linux, MacOS and Windows. In general however developing under a Linux, Mac or another Unix derivative is recommended.

First of all the BALL source code is required. If you want to actively develop for BALL you will also need the current BALL development version. Even if you just want to use BALL the development sources are recommended as they usually contain important bug fixes and enhancements that are not present in the packages released on the website.

The source of BALL is managed using the git source code management system. For Unix systems git packages are available in the repositories of your distribution. Windows packages are available on the git website. For a short introduction into git can be found here.

After having installed git it is time to get the BALL sources. Just issue the following command from a terminal:

git clone https://github.com/ball-project/ball.git

From this point on setting up your working environment differs between Unix and Windows.

Unices

For building under a Unix system there are essentially two possible ways of building available. Both be described in the following. They mainly differ in the way how external dependencies are made ready. Starting with release 1.4, the older autobuild-based system will no longer be supported.

CMake

The CMake build system per default allows out of source builds. This means, that the build system will not touch the existing source folders, but rather store the files it generates into a dedicated folder. As with the old autotools build system you must still install the development packages of the required dependencies. The detection of the latter however proves to be much more reliable.

1. Install the development packages (in most distributions these are called packagename-devel) of:

   • =Qt 4.6.x

   • Boost >= 1.42
   • Eigen >= 3.x
   • OpenGL (for VIEW) (this package might be called something like mesa-devel).
   • Glew (optional, for VIEW)
   • Python 2.7 (optional)
   • FFTW 3 (optional)
   • lpsolve (optional)
   • libsvm (optional)
   • tbb (optional, for VIEW and Real-time ray tracing)

2. Additionally you will need the following development tools:

   • !Lex/Flex
   • !Yacc/Bison

   • = sip-4.12 (optional) (e.g. necessary packages for Kubuntu can be found here).

3. Enter the toplevel directory of BALL (the one containing the CMakeLists.txt file and the source and include folders)

4. Create a folder build and change into it

5. Call cmake ..

   • If you want to install BALL locally add the following switch

   -DCMAKE_PREFIX_PATH=/your/prefix
   

6. Type make

7. If you want to install BALL type make install

If you chose to install BALL via make install into the default path you should be able to compile programs without needing to make any changes. If you just compiled BALL you will need to specify the library lookup path as well as two include paths when compiling a BALL application. This is because of the out of source build done by CMake. Here are the options you would have to set for g++, for example:

g++ -std=c++0x -I/path/to/BALL/include -I/path/to/BALL/build/include -L/path/to/BALL/build/lib

Alternatively, you can use CMake for your programs yourself, as described in developing external code using BALL.

If you just want to use BALLView, you can continue at BALLView.

Autobuild aka "The easy but slow way"

This will automatically download and compile all external dependencies. Note that on Linux Systems we strongly recommend to use your distributions package manager

1. Change into the "source" folder of BALL

2. Type ./autobuild If you already have successfully built the package answer "yes" and enter the path to the compiled package. Else you are unlucky and answer "no". The script will download the contrib package and compile it. Go and grab some drinks.

3. If there are no errors BALL should be built automatically. Grab some more drinks.

4. Type make install to move the built libraries to the "lib" directory that resides next to the BALL directory.

Windows

First, make sure that you have installed >= CMake 2.8.3 Next, assume that you put the BALL sources in C:\BALL and extracted the contrib zip archive for Windows to C:\BALL\Windows\contrib. Then, open a Visual Studio (>=2010) command shell and enter:

cd C:\BALL
mkdir build
cd build
cmake .. -G"Visual Studio 10 Win64" -DBALL_CONTRIB_PATH=C:\BALL\Windows\Contrib -DBALL_COMPLEX_PRECISION=double -DBALL_ENABLE_PACKAGING=true -DBALL_BUILD_SOLUTION_PARALLEL=ON
devenv BALL.sln

Eventually, you might have to give the full path to cmake. Afterwards, a Visual Studio solution file adapted to your installation should have been generated and opened.

On Windows, you have to do several things first:

• Install Intel Threading Building Blocks (TBB) and set the following environment variables:

TBB_INSTALL_DIR=<root_of_tbb_where_include_and_lib_directories_are>
TBB_ARCH_PLATFORM=intel64\vc10

• Install pre-build Qt 4.8.X version. If you plan building 64-bit BALL, you have to compile Qt yourself. Do not forget to set QTDIR system variable pointing to your QT installation folder.
• If you plan on using the Python interface, you will need to install Python. Currently, BALL does not support Python >= 3.0, so make sure to use a recent 2.x version. Also, if you plan on building Debug version of BALL, you have to modify <python_dir>/include/pyconfig.h, you have to comment out the following lines:

#ifdef _DEBUG
  #define Py_DEBUG
#endif

and replace this line

#pragma comment(lib,"python27_d.lib")

with this line

#pragma comment(lib,"python27.lib")

The reason is that otherwise in Debug build a debug version of Python will be used, which is however not supplied with standard Python installer. You can alternatively build debug version of python yourself but that is not recommended.