mitsuba/doc/compiling.tex

259 lines
14 KiB
TeX
Raw Normal View History

\section{Compiling the renderer}
2011-07-06 23:52:02 +08:00
\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.
2011-05-30 18:17:46 +08:00
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}
2011-05-30 18:17:46 +08:00
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 also want 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}:
2011-05-30 18:17:46 +08:00
\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}
2011-06-01 08:20:53 +08:00
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
2011-06-02 00:32:55 +08:00
build/config-icl12-msvc2010-win32.py
build/config-icl12-msvc2010-win64.py
\end{shell}
2011-07-06 23:52:02 +08:00
\subsection{Compilation flags}
\label{sec:compiling-flags}
Usually, you will not have to make any modification to this file, but sometimes a few minor
2011-05-30 18:17:46 +08:00
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}
2011-05-30 18:17:46 +08:00
\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.
2010-10-14 05:20:20 +08:00
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.
2011-07-06 23:52:02 +08:00
\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}.
2010-12-01 08:52:27 +08:00
\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
2010-12-01 08:52:27 +08:00
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},
2011-05-30 18:17:46 +08:00
as well as \code{MTS\_HAS\_COHERENT\_RT}.
\subsection{Building on Ubuntu Linux}
You'll first need to install a number of dependencies. It is assumed here
that you are using Ubuntu Linux, hence some of the package may be named differently if you are
using another distribution.
First, run
\begin{shell}
2010-10-05 20:09:38 +08:00
$\text{\$}$ sudo apt-get install build-essential scons qt4-dev-tools scons libpng12-dev libjpeg62-dev libilmbase-dev libopenexr-dev libxerces-c-dev libboost-dev libglewmx1.5-dev libxxf86vm-dev libboost-system-dev libboost-filesystem-dev
\end{shell}
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.2-2_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 also 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}.
\subsection{Building on Fedora Core}
You'll first need to install a number of dependencies. It is assumed here
that you are using Fedora Core, hence some of the package may be named differently if you are
using another distribution.
First, run
\begin{shell}
2010-09-22 08:41:30 +08:00
$\text{\$}$ yum install mercurial gcc-c++ scons boost-devel qt4-devel OpenEXR-devel xerces-c-devel
\end{shell}
2010-10-05 20:09:38 +08:00
You will also need the \texttt{glew-mx} and \texttt{collada-dom} packages, which are not included in the Fedora package repository.
You can grab source, \texttt{i386}, and \text{x86\_64} \texttt{RPM} files at the following location: \texttt{http://www.mitsuba-renderer.org/releases}.
After installing them, simply run
2010-10-05 20:09:38 +08:00
\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 also 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}.
2010-10-05 20:09:38 +08:00
\subsection{Building on Arch Linux}
There are two ways to install Mitsuba on Archlinux, the Arch way, and the other way.
2010-10-05 20:09:38 +08:00
The Arch Way is to use the Aur software repository.
Accessing software in the Aur repository is easiest when using a script called \texttt{packer}.
First download packer then use \texttt{makepkg} to build and install it.
The \texttt{-is} flags will prompt you for your sudo password and then install the package after it has finished building as well as install any needed dependencies.
2010-10-05 20:09:38 +08:00
\begin{shell}
$\text{\$}$ mkdir packer && cd packer
$\text{\$}$ wget http://aur.archlinux.org/packages/packer/packer/PKGBUILD
$\text{\$}$ makepkg -is
2010-10-05 20:09:38 +08:00
\end{shell}
Next, use packer to automatically download, build, and install Mitsuba as well as any needed dependencies.
The optional \code{--noedit} flag is used if you do not wish to edit the files after they are downloaded.
The optional \code{--noconfirm} flag is used if you do not wish to confirm each step of the installation.
2010-10-05 20:09:38 +08:00
\begin{shell}
$\text{\$}$ sudo packer -S --noedit --noconfirm mitsuba-hg glewmx collada-dom
2010-10-05 20:09:38 +08:00
\end{shell}
Periodically you may wish to update Mitsuba to the latest version.
To do this simply reinstall it and packer will pull and build the latest version.
\begin{shell}
$\text{\$}$ sudo packer -S --noedit --noconfirm mitsuba-hg
\end{shell}
Alternatively you can skip using packer and manually download the files and install them one at a time yourself.
First install glewmx
\begin{shell}
$\text{\$}$ mkdir glewmx && cd glewmx
$\text{\$}$ wget http://aur.archlinux.org/packages/glewmx/glewmx/PKGBUILD
$\text{\$}$ makepkg -is
\end{shell}
And then collada-dom
\begin{shell}
$\text{\$}$ mkdir collada-dom && cd collada-dom
$\text{\$}$ wget http://aur.archlinux.org/packages/collada-dom/collada-dom/PKGBUILD
$\text{\$}$ makepkg -is
\end{shell}
And finally Mitsuba
\begin{shell}
$\text{\$}$ mkdir mitsuba-hg && cd mitsuba-hg
$\text{\$}$ wget http://aur.archlinux.org/packages/mitsuba-hg/mitsuba-hg/PKGBUILD
$\text{\$}$ makepkg -is
\end{shell}
To uninstall do this
\begin{shell}
$\text{\$}$ sudo pacman -R mitsuba-hg glewmx collada-dom
\end{shell}
After installing you will be able to run the renderer from the command line.
Having set up everything, you can now move on to \secref{basics}.
If for some reason you are unable access the Aur files, they are also hosted at
(\url{https://www.mitsuba-renderer.org/releases/contrib/archlinux/}).
\subsection{Building on Windows}
On the Windows platform, Mitsuba already includes most of the dependencies in precompiled form.
You will still need to set up a few things though: first, you need to install Python
2011-06-05 23:26:30 +08:00
(\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}) 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.
Next, you will either need to compile Qt 4.7 (or a newer version) from
source or grab pre-built binaries (e.g. from
\url{http://code.google.com/p/qt-msvc-installer}).
It is crucial that the Qt build configuration \emph{exactly} matches that of Mitsuba:
2011-06-05 23:26:30 +08:00
for instance, if you were planning to use the 64-bit compiler in Visual
Studio 2010, both projects must be built with that exact same compiler.
2011-06-05 23:26:30 +08:00
When building Qt from source, an important point is to install any
Visual Studio service packs prior to this step---for instance, 64-bit
Qt binaries always crash when built with a Visual Studio 2010 installation
that is missing SP1. Once that is take care of, start the correct Visual Studio command
prompt, and enter
\begin{shell}
2011-05-30 18:17:46 +08:00
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}
2011-05-30 18:17:46 +08:00
inside the Qt directory.
2011-06-01 09:06:25 +08:00
Having installed all dependencies, run the ``Visual Studio \emph{2008/2010} Command
2010-11-22 02:03:56 +08:00
Prompt'' from the Start Menu (\code{x86} for 32-bit or \code{x64} for 64bit). Afterwards,
2011-06-01 09:06:25 +08:00
navigate to the Mitsuba directory.
2011-05-30 18:17:46 +08:00
Depending on whether or not the Qt binaries are on the \code{\%PATH\%}
2011-06-05 23:26:30 +08:00
environment variable, you might have to explicitly specify the Qt path:
2011-05-30 18:17:46 +08:00
\begin{shell}
2011-06-01 09:06:25 +08:00
C:\Mitsuba\>$\texttt{set}$ QTDIR=C:\Qt
2011-05-30 18:17:46 +08:00
\end{shell}
where \code{C:$\backslash$Qt} is the path to your Qt installation.
2011-06-01 09:06:25 +08:00
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.
2010-08-11 06:38:22 +08:00
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 now located in the \code{dist} directory, and they should be executed directly from there.
\subsubsection{Integration with the Visual Studio interface}
2011-06-01 09:26:23 +08:00
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
2011-06-01 09:26:23 +08:00
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
2011-06-05 23:26:30 +08:00
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 (\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}).