mitsuba/doc/compiling.tex

\section{Compiling the renderer}
\label{sec:compiling}
To compile Mitsuba, you will need a recent C++ compiler (e.g. GCC 5.3+ or
Visual Studio 2017) and some additional libraries, which Mitsuba uses internally.
Builds on all supported platforms are done using a unified system
based on SCons\footnote{Mitsuba's configuration files are written for SCons 2.x. SCons 3 can be used by manually upgrading the relevant configuration files.} (\url{http://www.scons.org}), which is a Python-based
software construction tool. The exact process is different depending on
which operating system is used and will be explained in the following subsections.

\subsection{Common steps}
To get started, you will need to download a recent version of the Mitsuba source code. Before
doing this, ensure that you have read the licensing agreement
(\secref{license}), and that you abide by its contents. Note that, being a ``viral''
license, the GPL automatically applies to derivative work. Amongst other things, this
means that Mitsuba's source code is \emph{off-limits} to those who develop rendering
software not distributed under a compatible license.

Check that the Git (\url{https://git-scm.com/}) versioning system\footnote{On
Windows, you might want to use the convenient TortoiseGit shell extension
(\url{https://tortoisegit.org/}) to run the subsequent steps directly from the
Explorer.} is installed, which is required to fetch the most recent source code
release.
Begin by entering the following at the command prompt (or run an equivalent command from a graphical Git frontend):
\begin{shell}
$\texttt{\$}$ git clone https://github.com/mitsuba-renderer/mitsuba
\end{shell}
This should dowload a full copy of the main repository.

\subsubsection{Build configurations}
Common to all platforms is that a build configuration file must be selected. Several options are
available on each operating system:
\paragraph{Linux:}
On Linux, there are two supported configurations:
\begin{description}
\item[\code{build/config-linux-gcc.py}:] Optimized single precision GCC build. The resulting binaries include debug symbols for convenience, but these can only be used for relatively high-level debugging due to the enabled optimizations.
\item[\code{build/config-linux-gcc-debug.py}:] Non-optimized single precision GCC build with debug symbols. When compiled with this configuration, Mitsuba
will run extremely slowly. Its main use is to track down elusive bugs.
\end{description}
\paragraph{Windows:}
On Windows, builds can be performed using the Visual Studio 2017\footnote{No other Visual Studio versions are currently supported.}
compiler.
\begin{description}
\item[\code{build/config-win64-\{msvc2017, msvc2017-debug\}.py}:] Create 64 bit binaries using Microsoft Visual C++ version 2017.
The configurations with the suffix \code{-debug} will include debug symbols in all binaries, which run very slowly.
\end{description}
\paragraph{Mac OS:}
On Mac OS, builds can be performed using the XCode 8 \code{clang-llvm} toolchain.
It is possible to target MacOS 10.12 (Sierra) as the oldest supported operating system release.
XCode must be installed along with the supplementary Command Line Tools.
\begin{description}
\item[\code{config-macos-10.12-clang-x86\_64.py}:] Creates 64-bit binaries using the \code{clang-llvm} toolchain.
\end{description}
Note that the configuration files assume that XCode was
installed in the \code{/Applications} folder. They must be manually updated
when this is not the case.
\subsubsection{Selecting a configuration}
Having chosen a configuration, copy it to the main directory and rename it to \code{config.py}, e.g.:
\begin{shell}
$\texttt{\$}$ cp build/config-linux-gcc.py config.py
\end{shell}

\subsection{Compilation flags}
\label{sec:compiling-flags}
There are several flags that affect the behavior of Mitsuba and must be specified at compile time.
These usually don't need to be changed, but if you want to compile Mitsuba for spectral rendering, or
to use double precision for internal computations then the following may be useful. Otherwise, you may skip ahead to the subsection
that covers your operating system.

To change the compilation flags, open the \code{config.py} file that was just copied and look up the \code{CXXFLAG} parameter.
The following options are available:
\begin{description}
\item[\texttt{MTS\_DEBUG}] Enable assertions etc. Usually a good idea, and
enabled by default (even in release builds).
\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.
Refer also to \secref{colorspaces}.
\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}]Causes the GUI to use a software
fallback instead of the hardware-accelerated realtime preview.
This is useful when the binary will be executed over a remote link using a
protocol such as RDP (which does not provide the requisite OpenGL features).
\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 Debian or Ubuntu Linux}
\label{sec:compiling-ubuntu}
You'll first need to install a number of dependencies. It is assumed here that you are using a
recent version of Ubuntu Linux (Xenial Xerus / 16.04 LTS or later), hence some of the
package may be named differently if you are using Debian Linux or another Ubuntu version.

First, run
\begin{shell}
$\text{\$}$ sudo apt-get install build-essential scons git libpng12-dev
    libjpeg-dev libilmbase-dev libxerces-c-dev libboost-all-dev libopenexr-dev
    libglewmx-dev libxxf86vm-dev libeigen3-dev libfftw3-dev
\end{shell}
To get COLLADA support, you will also need to install the \texttt{collada-dom} packages:
\begin{shell}
$\text{\$}$ sudo apt-get install libcollada-dom-dev
\end{shell}
If you want to build the GUI as well, you will need to install the Qt 5 development libraries:
\begin{shell}
$\text{\$}$ sudo apt-get install qt5-default libqt5opengl5-dev libqt5xmlpatterns5-dev
\end{shell}
To start a regular build\footnote{If you have multiple Qt versions installed, you may need to select Qt 5 as the library version by running e.g.: \code{QT\_SELECT=qt5 scons} }, 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} or \code{--parallelize} (uses all available cores) to the \code{scons} command.
If all goes well, SCons should finish successfully within a few minutes:
\begin{shell}
scons: $\texttt{done}$ building targets.
\end{shell}
To run the renderer from the command line, you first have to import it into your shell environment:
\begin{shell}
$\text{\$}$ source setpath.sh
\end{shell}
Having set up everything, you can now move on to \secref{basics}.
\subsubsection{Creating Debian or Ubuntu Linux packages}
The preferred way of redistributing executables on Debian or Ubuntu Linux is to create
\code{.deb} package files. To make custom Mitsuba packages, it is strongly recommended
that you work with a pristine installation of the target operating system\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 most recent operating system release
to a subdirectory. The following example is based on Ubuntu 12.04 LTS (``Precise Pangolin''),
but the steps are almost identical for other versions of Ubuntu or Debian Linux.
\begin{shell}
$\text{\$}$ sudo apt-get install debootstrap
$\text{\$}$ sudo debootstrap --arch amd64 precise precise-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 precise-pristine
$\text{\$}$ echo "deb http://archive.ubuntu.com/ubuntu precise 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{\$}$ git clone https://github.com/mitsuba-renderer/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 or a local network, 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. This setup is convenient for
distributing a custom Mitsuba build to many Debian or Ubuntu machines running (e.g. to nodes in a rendering cluster).
\subsection{Building on Fedora Core}
You'll first need to install a number of dependencies. It is assumed here
that you are using FC27, hence some of the package may be named differently if you are
using another version.

First, run
\begin{shell}
$\text{\$}$ sudo yum install git gcc-c++ scons boost-devel qt5-devel qt5-qtxmlpatterns-devel OpenEXR-devel xerces-c-devel python-devel glew-devel libpng-devel libjpeg-devel collada-dom-devel eigen3-devel fftw3-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 run the renderer from the command line, you first have to import it into your shell environment:
\begin{shell}
$\text{\$}$ source setpath.sh
\end{shell}
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{\$}$ sudo 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 qt5 scons git 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}
Finally, Eigen 3 must be installed. Again, there is a binary package on the
Mitsuba website and the corresponding \code{PKGBUILD} can be obtained here:
\url{http://aur.archlinux.org/packages.php?ID=47884}.
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} or \code{--parallelize} (uses all available cores) 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 run the renderer from the command line, you first have to import it into your shell environment:
\begin{shell}
$\text{\$}$ source setpath.sh
\end{shell}

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}

% This is currently outdated
%\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}
Compiling Mitsuba's dependencies on Windows is a laborious process; for convenience, there
is a repository that provides them in precompiled form. To use this repository, clone it
using Git and rename the directory so that it forms the \code{dependencies} subdirectory
inside the main Mitsuba directory, i.e. run something like
\begin{shell}
C:\>cd mitsuba
C:\mitsuba\>git clone https://github.com/mitsuba-renderer/dependencies_win64 dependencies
\end{shell}
There are a few other things that need to be set up: make sure that your
installation of Visual Studio is up to date, since Mitsuba binaries created with versions prior to 2017 will not link or crash.

Next, you will need to install Python 2.7.x
(\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, or install a 32-bit version of Python.}
(\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.

Having installed all dependencies, run the ``x64 Native Tools Command Prompt
for VS \emph{2017}'' from the Start Menu,
navigate to the Mitsuba directory, and 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} or \code{--parallelize} (uses all available cores) to the \code{scons} command.

If all goes well, the build process will finish successfully after a few
minutes. \emph{Note} that 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 2017 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-msvc2017.sln}
and \code{build/mitsuba-msvc2017.vcxproj}. 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.

\subsection{Building on Mac OS X}
\vspace{-5mm}
\remarks{
    \item Unfortunately, OpenMP is not available when compiling
    using the regular \code{clang} toolchain.
    This will cause the following parts of Mitsuba
    to run single-threaded: bitmap resampling (i.e. MIP map generation),
    blue noise point generation in the \pluginref{dipole}
    plugin, as well as the \pluginref{ppm} and \pluginref{sppm} plugins.
    \item The pre-compiled dependencies do not include the \code{collada-dom}
    library.
    It is possible to install it with Homebrew (\url{https://brew.sh/},
    then run \code{brew install collada-dom})
    and then adding the \code{include} folder paths and library name to \code{config.py}.
    By default, they should look like this:
    \begin{python}
      COLLADAINCLUDE = ['/usr/local/include/collada-dom2.4', '/usr/local/include/collada-dom2.4/1.4']
      COLLADALIBDIR  = ['/usr/local/Cellar/collada-dom/2.4.4/lib']
      COLLADALIB     = ['collada-dom2.4-dp']
    \end{python}
    \item To build the Mitsuba GUI, you need a working Qt 5 installation.
    You may install it with Homebrew (\code{brew install qt}) or by downloading
    the appropriate package from \url{https://qt.io}.
}
Compiling Mitsuba's dependencies on Mac OS is a laborious process; for convenience, there
is a repository that provides them in precompiled form. To use this repository, clone it
using Git and rename the directory so that it forms the \code{dependencies} subdirectory
inside the main Mitsuba directory, i.e. run something like
\begin{shell}
$\text{\$}$ cd mitsuba
$\text{\$}$ git clone https://github.com/mitsuba-renderer/dependencies_macos dependencies
\end{shell}
You will also need to install SCons (>2.0.0, available at \code{www.scons.org}) and
a recent release of XCode, including its command-line compilation tools. Next, 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} or \code{--parallelize} (uses all available cores) 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 run the renderer from the command line, you first have to import it into your shell environment:
\begin{shell}
$\text{\$}$ source setpath.sh
\end{shell}