****************
Building PolyVox
****************

Requirements
============

To build PolyVox you need:

* `CMake <http://cmake.org>`_ 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 <http://qt.nokia.com>`_ for building the tests and the example applications
	* ``qcollectiongenerator`` which comes with Qt Assistant is used for bundling the docs for installation
* `Doxygen <http://doxygen.org>`_ for building the documentation. Version 1.5.7 is needed to build the Qt Assistant docs. 1.7.0 or greater is recommended
* `Python <http://python.org>`_, `Sphinx <http://sphinx.pocoo.org>`_ and `PyParsing <http://pyparsing.wikispaces.com/>`_ for generating the PolyVox manual in HTML
* `Python development libraries <http://python.org>`_, `SWIG <http://swig.org/>`_ 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 <http://sphinx.pocoo.org>`_ 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 <http://cmake.org/cmake/resources/software.html>`_. 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.
