Building PolyVox

Requirements

To build PolyVox you need:

  • CMake 2.8.3 or greater
  • A C++ compiler with support for some C++0x features (GCC 4.3 or VC 2010 seem to work)

With the following optional packages:

  • Qt for building the tests and the example applications
    • qcollectiongenerator which comes with Qt Assistant is used for bundling the docs for installation
  • Doxygen for building the documentation. Version 1.5.7 is needed to build the Qt Assistant docs. 1.7.0 or greater is recommended

  • Python, Sphinx and PyParsing for generating the PolyVox manual in HTML

  • Python development libraries, SWIG for generating the Python bindings

Linux

Navigate to the PolyVox source directory (the directory containing INSTALL.txt etc.) with and then enter the build directory with:

cd build

CMake

Now, we use CMake to generate the makefiles with:

cmake ..

The .. tells CMake to look in the parent directory for the source.

By default this will set it to be installed in /usr/local so if you want to install it elsewhere, set the CMAKE_INSTALL_PREFIX variable to the path you want to install to.

You can set CMake variables by passing -D<variable>:<type>=<value> to the cmake command (the :<type> part is optional but recommended). For example, to set the install prefix, pass:

-DCMAKE_INSTALL_PREFIX:PATH=/whatever/you/want

The other available settings for PolyVox are:

ENABLE_EXAMPLES (ON or OFF)
Build the example applications that come with PolyVox. Defaults to ON.
ENABLE_TESTS (ON or OFF)
Build the test applications that come with PolyVox. Running the tests is detailed in the next section. Defaults to ON.
ENABLE_BINDINGS (ON or OFF)
Should the Python bindings to PolyVox be built. This requires the Python development libraries and SWIG to be installed. Defaults to ON.
LIBRARY_TYPE (DYNAMIC or STATIC)
Choose whether static (.a) or dynamic libraries (.so) should be built. On Linux DYNAMIC is the default and on Windows STATIC is the default.
CMAKE_BUILD_TYPE (Debug, Release, RelWithDebInfo or MinSizeRel)

String option to set the type of build. This will automatically set some compilation flags such as the optimisation level or define NDEBUG.

For development work against the library
Use Debug or RelWithDebInfo
For your final version
Use Release
For building packages (e.g. for Linux distributions)
Use RelWithDebInfo

Building and installing

Once this has completed successfully, simply run:

make install

and all should work.

Testing

To run the tests you do not need to have run make install. Simply run:

make
make test

API Documentation

If you want to generate the API documentation, you’ll need Doxygen installed. If you saw API Docs available: YES at the end of the CMake output then you’re all set. To generate the docs, just run:

make doc

and the documentation can be browsed in plain HTML form at <build directory>/library/doc/html/index.html.

On top of this, if qcollectiongenerator is installed, PolyVox can also compile and install this documentation as a Qt Help Collection file to <prefix>/share/doc/packages/polyvox/qthelp/polyvox.qhc (this file is in the build directory as <build directory>/library/doc/qthelp/polyvox.qhc). To view this file you need Qt Assistant installed. You can open it with:

assistant -collectionFile library/doc/qthelp/polyvox.qhc

This allows indexed searching of the documentation and easier browsing.

Manual

As well as the API documentation, PolyVox also provides a user manual. This is written using Sphinx and so to convert the documentation sources to HTML requires Sphinx and Python to be installed. If these are installed and found then you will see Build manual: YES in the CMake summary output. If this is the case then just run:

make manual

and the HTML manual will be available at <build directory>/documentation/index.html.

If you have Sphinx installed but you do not get the confirmation in the CMake output, you may need to set SPHINXBUILD_EXECUTABLE to the location of your sphinx-build executable.

If you do not have Python and Sphinx installed and do not want to install them then the manual is just plain text (.rst files) which are readable in their plain form in the documentation directory of the source distribution.

Windows

For information about the dependencies, CMake configuration variables and buildable targets look at the Linux build information in the section above.

CMake

You need CMake installed so get the binary distribution from CMake.org. Install it and run the CMake GUI.

Point the source directory to the directory holding this file and the build directory to the build subdirectory. Then, click the Configure button. Click through the dialog box that appears and once you’ve clicked Finish you should see text appearing in the bottom text area. Once this has finished, some options will appear in the top area. The purpose of these options in detailed in the Linux→CMake section above. Once you have set these options to what you please, click Configure again. If it completes without errors then you can click Generate which will generate your compilers project files in the build directory.

Building

Open the project files in your IDE and build the project as you normally would.

Table Of Contents

Previous topic

Prerequisites

Next topic

Principles of PolyVox

This Page