mitsuba/doc/compiling.tex

\section{Compiling the renderer}
\label{sec:compiling}
To compile Mitsuba, you will need a recent C++ compiler (e.g. GCC 4.1+ or 
Visual Studio 2008+) and some additional libraries, which Mitsuba uses internally. 
Builds on all supported platforms are done using a unified system
based on SCons (\url{http://www.scons.org}), which is a Python-based 
software construction tool. There are some differences between the different operating systems---for
more details, please refer to one of the next sections depending on which one you use.

\subsection{Common steps}
To get started, you will need to download a recent version of Mitsuba. Make sure that you have the Mercurial (\url{http://mercurial.selenic.com/}) versioning system installed\footnote{On Windows, you might want to use the convenient TortoiseHG shell extension (\url{http://tortoisehg.bitbucket.org/}) to run the subsequent steps directly from the Explorer.} and enter the following at the command prompt:
\begin{shell}
$\texttt{\$}$ hg clone https://www.mitsuba-renderer.org/hg/mitsuba
\end{shell}
Afterwards, you will need to download the precompiled dependencies into a new
subdirectory named \code{mitsuba/dependencies}:
\begin{shell}
$\texttt{\$}$ cd mitsuba
$\texttt{\$}$ hg clone https://www.mitsuba-renderer.org/hg/dependencies
\end{shell}
Common to all platforms is that a build configuration file must be chosen: amongst the
following, please copy the best matching file into a new file to the root of the Mitsuba
directory and rename it into \code{config.py}.
\begin{shell}
build/config-linux.py  
build/config-darwin-x86_64.py  
build/config-darwin-x86.py  
build/config-darwin-universal.py  
build/config-msvc2008-win32.py  
build/config-msvc2008-win64.py
build/config-msvc2010-win32.py  
build/config-msvc2010-win64.py
build/config-icl12-msvc2010-win32.py
build/config-icl12-msvc2010-win64.py
build/config-icl12-darwin-x86_64.py
build/config-icl12-darwin-x86.py
\end{shell}

\subsection{Compilation flags}
\label{sec:compiling-flags}
Usually, you will not have to make any modification to this file, but sometimes a few minor 
edits may be necessary. In particular, you might want to add or remove certain
compilation flags from the \code{CXXFLAGS} parameter. The following settings
affect the behavior of Mitsuba:
\begin{description}
\item[\texttt{MTS\_DEBUG}] Enable assertions etc. Usually a good idea, and
enabled by default.
\item[\texttt{MTS\_KD\_DEBUG}] Enable additional checks in the kd-Tree. This
is quite slow and mainly useful to track down bugs when they are suspected.
\item[\texttt{MTS\_KD\_CONSERVE\_MEMORY}] Use a more compact representation 
for triangle geometry (at the cost of speed). This flag causes Mitsuba to use the somewhat slower
Moeller-Trumbore triangle intersection method instead of the default Wald
intersection test, which has an overhead of 48 bytes per triangle.
Off by default.
\item[\texttt{MTS\_SSE}]Activate optimized SSE routines. On by default.
\item[\texttt{MTS\_HAS\_COHERENT\_RT}]Include coherent ray tracing support (depends on \texttt{MTS\_SSE}). This flag is activated by default. 
\item[\texttt{MTS\_DEBUG\_FP}]Generated NaNs and overflows will cause floating point exceptions, which can be caught in a debugger. This is slow and mainly meant as a debugging tool for developers. Off by default.
\item[\texttt{SPECTRUM\_SAMPLES=}$\langle ..\rangle$]This setting defines the number of spectral samples (in the 368-830 $nm$ range) that are used to render scenes. The default is 3 samples, in which case the renderer automatically turns into an RGB-based system. For high-quality spectral rendering, this should be set to 30 or higher.
\item[\texttt{SINGLE\_PRECISION}] Do all computation in single precision. This is normally sufficient and therefore used as the default setting.
\item[\texttt{DOUBLE\_PRECISION}] Do all computation in double precision. This flag is incompatible with
\texttt{MTS\_SSE}, \texttt{MTS\_HAS\_COHERENT\_RT}, and \texttt{MTS\_DEBUG\_FP}.
\item[\texttt{MTS\_GUI\_SOFTWARE\_FALLBACK}]Forces the GUI to use a software
fallback mode, which is considerably slower and removes the realtime preview.
This is useful when running the interface on a remote Windows machine
accessed via the Remote Desktop Protocol (RDP).
\end{description}
All of the default configurations files located in the \texttt{build} directory use the flags 
\code{SINGLE\_PRECISION}, \code{SPECTRUM\_SAMPLES=3}, \code{MTS\_DEBUG}, \code{MTS\_SSE},
as well as \code{MTS\_HAS\_COHERENT\_RT}.

\subsection{Building on Ubuntu Linux}
\label{sec:compiling-ubuntu}
You'll first need to install a number of dependencies. It is assumed here
that you are using Ubuntu Linux (Maverick Meerkat / 10.10 or later), hence some of the package may be named differently if you are 
using another version.

First, run
\begin{shell}
$\text{\$}$ sudo apt-get install build-essential scons mercurial qt4-dev-tools libpng12-dev 
    libjpeg62-dev libilmbase-dev libxerces-c3-dev libboost1.42-all-dev 
	libopenexr-dev libglewmx1.5-dev libxxf86vm-dev libpcrecpp0
	libboost-system-dev libboost-filesystem-dev libboost-python-dev libboost-dev
\end{shell}
Please ensure that the installed version of the boost libraries is 1.42 or later.
To get COLLADA support, you will also need to install the \texttt{collada-dom} packages or build it from scratch. Here, we install the \code{x86\_64} binaries and development headers that can be found in the \texttt{dependencies/linux} directory\footnote{The directory also contains source packages in case these binaries don't work for you.}:
\begin{shell}
$\text{\$}$ sudo dpkg --install collada-dom_2.3.1-1_amd64.deb collada-dom-dev_2.3.1-1_amd64.deb
\end{shell}
Afterwards, simply run
\begin{shell}
$\text{\$}$ scons
\end{shell}
inside the Mitsuba directory. In the case that you have multiple processors, you might want to parallelize the build by appending \code{-j }\emph{core count} to the command.
If all goes well, SCons should finish successfully within a few minutes:
\begin{shell}
scons: $\texttt{done}$ building targets.
\end{shell}
To be able to run the renderer from the command line, you will first have to import it into your path:
\begin{shell}
$\text{\$}$ . setpath.sh
\end{shell}
(note the period at the beginning -- this assumes that you are using \code{bash}).
Having set up everything, you can now move on to \secref{basics}.
\subsubsection{Creating Ubuntu packages}
For Ubuntu, the preferred way of redistristributing executables is to create
\code{.deb} package files. To create Mitsuba packages, it is strongly recommended
that you work with a pristine Ubuntu installation\footnote{Several commercial graphics 
drivers ``pollute'' the OpenGL setup so that the compiled Mitsuba binaries 
can only be used on machines using the same drivers. For this reason, it is 
better to work from a clean boostrapped install.}. This can be done as follows:
first, install \code{debootstrap} and download the latest version of Ubuntu
to a subdirectory (here, we use Maverick Meerkat, or version 10.10)
\begin{shell}
$\text{\$}$ sudo apt-get install debootstrap
$\text{\$}$ sudo debootstrap --arch amd64 maverick maverick-pristine
\end{shell}
Next, \code{chroot} into the created directory, enable the \code{multiverse} package repository,
and install the necessary tools for creating package files:
\begin{shell}
$\text{\$}$ sudo chroot maverick-pristine
$\text{\$}$ echo "deb http://archive.ubuntu.com/ubuntu maverick universe" >> /etc/apt/sources.list
$\text{\$}$ apt-get update
$\text{\$}$ apt-get install debhelper dpkg-dev pkg-config
\end{shell}
Now, you should be able to set up the remaining dependencies as described in \secref{compiling-ubuntu}.
Once this is done, check out a copy of Mitsuba to the root directory of the \code{chroot} environment, e.g.
\begin{shell}
$\text{\$}$ hg clone https://www.mitsuba-renderer.org/hg/mitsuba
\end{shell}
To start the compilation process, enter
\begin{shell}
$\text{\$}$ cd mitsuba
$\text{\$}$ cp -R data/linux/debian debian
$\text{\$}$ dpkg-buildpackage -nc
\end{shell}
After everything has been built, you should find the created package files
in the root directory.
\subsubsection{Releasing Ubuntu packages}
To redistribute Ubuntu packages over the Internet, it is convenient to 
put them into an \code{apt}-compatible repository. To prepare such a
repository, put the two \code{deb}-files built in the last section, 
as well as the \code{collada-dom} \code{deb}-files into a public directory 
made available by a HTTP server and inside it, run
\begin{shell}
$path-to-htdocs\text{\$}$ dpkg-scanpackages path/to/deb-directory /dev/null | gzip -9c > path/to/deb-directory/Packages.gz
\end{shell}
This will create a respository index file named \code{Packages.gz}.
Note that you must execute this command in the root directory of the
HTTP server's web directory and provide the relative path to the 
package files -- otherwise, the index file will specify the wrong package 
paths. Finally, the whole directory can be uploaded to some public location
and then referenced by placing a line following the pattern
\begin{shell}
deb http://<path-to-deb-directory> ./
\end{shell}
into the \code{/etc/apt/sources.list} file.

\subsection{Building on Fedora Core}
You'll first need to install a number of dependencies. It is assumed here
that you are using FC15, hence some of the package may be named differently if you are 
using another version.

First, run
\begin{shell}
$\text{\$}$ yum install mercurial gcc-c++ scons boost-devel qt4-devel OpenEXR-devel xerces-c-devel python-devel glew-devel collada-dom-devel
\end{shell}
Afterwards, simply run
\begin{shell}
$\text{\$}$ scons
\end{shell}
inside the Mitsuba directory. In the case that you have multiple processors, you might want to parallelize the build by appending \code{-j }\emph{core count} to the command.
If all goes well, SCons should finish successfully within a few minutes:
\begin{shell}
scons: $\texttt{done}$ building targets.
\end{shell}
To be able to run the renderer from the command line, you will first have to import it into your path:
\begin{shell}
$\text{\$}$ . setpath.sh
\end{shell}
(note the period at the beginning -- this assumes that you are using \code{bash}).
Having set up everything, you can now move on to \secref{basics}.
\subsubsection{Creating Fedora Core packages}
To create \code{RPM} packages, you will need to install the \code{RPM} development tools:
\begin{shell}
$\text{\$}$ yum install rpmdevtools
\end{shell}
Once this is done, run the following command in your home directory:
\begin{shell}
$\text{\$}$ rpmdev-setuptree
\end{shell}
and create a Mitsuba source package in the appropriate directory:
\begin{shell}
$\text{\$}$ ln -s mitsuba mitsuba-$\code{\MitsubaVersion}$
$\text{\$}$ tar czvf rpmbuild/SOURCES/mitsuba-$\code{\MitsubaVersion}$.tar.gz mitsuba-$\code{\MitsubaVersion}$/.
\end{shell}
Finally, \code{rpmbuilder} can be invoked to create the package:
\begin{shell}
$\text{\$}$ rpmbuild -bb mitsuba-$\code{\MitsubaVersion}$/data/linux/fedora/mitsuba.spec
\end{shell}
After this command finishes, its output can be found in the directory \code{rpmbuild/RPMS}.
\subsection{Building on Arch Linux}
You'll first need to install a number of dependencies: 
\begin{shell}
$\text{\$}$ sudo pacman -S gcc xerces-c glew openexr boost libpng libjpeg qt scons mercurial python
\end{shell}
For COLLADA support, you will also have to install the \code{collada-dom}
library. For this, you can either install the binary package available on
the Mitsuba website, or you can compile it yourself using the \code{PKGBUILD}
supplied with Mitsuba, i.e.
\begin{shell}
$\text{\$}$ cd <some-temporary-directory>
$\text{\$}$ cp <path-to-mitsuba>/data/linux/arch/collada-dom/PKGBUILD .
$\text{\$}$ makepkg PKGBUILD
<..compiling..>
$\text{\$}$ sudo pacman -U <generated package file>
\end{shell}
Once all dependencies are taken care of, simply run
\begin{shell}
$\text{\$}$ scons
\end{shell}
inside the Mitsuba directory. In the case that you have multiple processors, you might want to parallelize the build by appending \code{-j }\emph{core count} to the command.
If all goes well, SCons should finish successfully within a few minutes:
\begin{shell}
scons: $\texttt{done}$ building targets.
\end{shell}
To be able to run the renderer from the command line, you will first have to import it into your path:
\begin{shell}
$\text{\$}$ . setpath.sh
\end{shell}
(note the period at the beginning -- this assumes that you are using \code{bash}).
Having set up everything, you can now move on to \secref{basics}.
\subsubsection{Creating Arch Linux packages}
Mitsuba ships with a \code{PKGBUILD} file, which automatically builds
a package from the most recent repository version:
\begin{shell}
$\text{\$}$ makepkg data/linux/arch/mitsuba/PKGBUILD
\end{shell}

\subsection{Compiling on Gentoo Linux}
Simon Haegler has contributed a Gentoo \code{ebuild} script that can be used to Mitsuba.
It can be found inside the user repository \code{git://git.overlays.gentoo.org/user/mistafunk.git}
and is located at \code{media-gfx/mitsuba/mitsuba-0.3.0.ebuild}.

\subsection{Building on Windows}
On the Windows platform, Mitsuba already includes many of the dependencies in precompiled form.
There are a few things to set up though. First, please make sure that your
installation of Visual Studio is up to date. In particular, for
Visual Studio 2010, you'll need to apply Service Pack 1
or the resulting Mitsuba executables will crash
(\url{http://www.microsoft.com/download/en/details.aspx?id=23691}).

Next, you will need to install Python 2.6.x \footnote{
Make sure that you get a Python binary matching the architecture, for which you plan to compile
Mitsuba (i.e. \code{x86} or \code{x86\_64}) -- this is needed by the Python bindings. If you wish to
use another Python version, you will have to change \code{config.py} and supply your own Boost boost 
binaries linked against that version of Python.} 
(\url{www.python.org}) and SCons \footnote{Note that on some Windows machines, the SCons 
installer generates a warning about not finding Python in the registry. In this case, you 
can instead run \code{python setup.py install} within the source release of SCons.} 
(\url{http://www.scons.org}, any 2.x version will do) and ensure that they are contained in the \code{\%PATH\%} 
environment variable so that entering \code{scons} on the command prompt (\code{cmd.exe}) 
launches the build system.

Finally, you will need to build Qt 4.7 (or a newer version) from 
source, as pre-built binaries will unfortunately not work. 
At the time of this writing, a suitable source code package is available here: \url{http://get.qt.nokia.com/qt/source/qt-everywhere-opensource-src-4.7.4.zip}.
It is important that the Qt build process
is performed using the \emph{exact same}\footnote{The blame here goes to 
Microsoft for changing the C++ ABI whenever they feel like it.} 
compiler that will also be used to build Mitsuba. This means that 
Qt should be compiled \emph{after} applying any Visual Studio service packs.
To configure Qt and start the compilation process, enter
\begin{shell}
C:\Qt>configure.exe -release -no-webkit -no-phonon -no-phonon-backend -no-script
      -no-scripttools -no-qt3support -no-multimedia -no-ltcg
..(configuration messages)..
C:\Qt>nmake
\end{shell}

Having installed all dependencies, run the ``Visual Studio \emph{2008/2010} Command 
Prompt'' from the Start Menu (\code{x86} for 32-bit or \code{x64} for 64bit). Afterwards,
navigate to the Mitsuba directory.
Depending on whether or not the Qt binaries are on the \code{\%PATH\%}
environment variable, you might have to explicitly specify the Qt path:
\begin{shell}
C:\Mitsuba\>$\texttt{set}$ QTDIR=C:\Qt
\end{shell}
where \code{C:$\backslash$Qt} is the path to your Qt installation.
Afterwards, simply run
\begin{shell}
C:\Mitsuba\>scons
\end{shell}
In the case that you have multiple processors, you might want to parallelize the build by appending the option \code{-j }\emph{core count} to the \code{scons} command.

If all goes well, the build process will finish successfully after a few
minutes. In comparison to the other platforms, you don't have to run the \code{setpath.sh} script at this point. 
All binaries are automatically copied into the \code{dist} directory, and they should be executed directly from there.

\subsubsection{Integration with the Visual Studio interface}
Basic Visual Studio 2008 and 2010 integration with support for code completion 
exists for those who develop Mitsuba code on Windows. 
To use the supplied projects, simply double-click on one of the two files \code{build/mitsuba-msvc2008.sln} 
and \code{build/mitsuba-msvc2010.sln}. These Visual Studio projects still internally
use the SCons-based build system to compile Mitsuba; whatever 
build configuration is selected within Visual Studio will be used to pick a matching
configuration file from the \texttt{build} directory. Note that you will
potentially have to add a \code{QTDIR=\"...\"} line to each of the
used configuration files when building directly from Visual Studio.

\subsection{Building on Mac OS X}
On Mac OS X, you will need to install both SCons (>2.0.0, available at \code{www.scons.org}) and 
a recent release of XCode. You will also need to get Qt 4.7.0 or a newer version
--- make sure that you get the normal Cocoa release (i.e. \emph{not} the one based on Carbon). All of the
other dependencies are already included in precompiled form.
Now open a Terminal and run
\begin{shell}
$\text{\$}$ scons
\end{shell}
inside the Mitsuba directory. In the case that you have multiple processors, you might want to parallelize the build by appending \code{-j }\emph{core count} to the command.
If all goes well, SCons should finish successfully within a few minutes:
\begin{shell}
scons: $\texttt{done}$ building targets.
\end{shell}
To be able to run the renderer from the command line, you will have to import it into your path:
\begin{shell}
$\text{\$}$ . setpath.sh
\end{shell}
(note the period at the beginning -- this assumes that you are using \code{bash}).