267 lines
14 KiB
TeX
267 lines
14 KiB
TeX
\section{Compiling the renderer}
|
|
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 three supported platforms are done using a unified system
|
|
based on SCons (\url{http://www.scons.org}), a flexible python-based
|
|
software construction tool. There are some minor differences between operating systems though: 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 and enter the following at the command prompt:
|
|
\begin{shell}
|
|
$\texttt{\$}$ hg clone https://www.mitsuba-renderer.org/hg/mitsuba
|
|
\end{shell}
|
|
On Windows, you can instead use the more convenient TortoiseHG shell extension (\url{http://tortoisehg.bitbucket.org/})
|
|
to do this directly from the Explorer.
|
|
|
|
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}
|
|
config/config-linux.py
|
|
config/config-darwin-x86_64.py
|
|
config/config-darwin-x86.py
|
|
config/config-darwin-universal.py
|
|
config/config-icl11-win32.py
|
|
config/config-icl11-win64.py
|
|
config/config-msvc2008-win32.py
|
|
config/config-msvc2008-win64.py
|
|
config/config-msvc2010-win32.py
|
|
config/config-msvc2010-win64.py
|
|
\end{shell}
|
|
|
|
Some minor adjustments may have to be made to this file based on your configuration.
|
|
You may also set adjust certain compilation flags here:
|
|
\begin{description}
|
|
\item[\texttt{MTS\_DEBUG}] Enable assertions etc. Usually a good idea.
|
|
\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 less memory for storing geometry (at the cost of speed).
|
|
Off by default.
|
|
\item[\texttt{SINGLE\_PRECISION}] Do all computation in single precision. This is usually sufficient.
|
|
\item[\texttt{DOUBLE\_PRECISION}] Do all computation in double precision. Incompatible with
|
|
\texttt{MTS\_SSE}, \texttt{MTS\_HAS\_COHERENT\_RT}, and \texttt{MTS\_DEBUG\_FP}.
|
|
\item[\texttt{MTS\_SSE}]Activate optimized SSE routines.
|
|
\item[\texttt{MTS\_HAS\_COHERENT\_RT}]Include coherent ray tracing support (depends on \texttt{MTS\_SSE}).
|
|
\item[\texttt{MTS\_DEBUG\_FP}]Generated NaNs will cause floating point exceptions, which can be caught in a debugger. Warning: This is slow!
|
|
\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 machine
|
|
accessed via the Remote Desktop Protocol (RDP).
|
|
\end{description}
|
|
All default configurations use the flags \code{MTS\_DEBUG}, \code{SINGLE\_PRECISION}, \code{MTS\_SSE}, \code{MTS\_HAS\_COHERENT\_RT}.
|
|
Initially, it is a good idea to just leave the configuration the way it is.
|
|
|
|
\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}
|
|
$\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 them from scratch. Here, we install the \code{x86\_64} binaries and development headers included with Mitsuba:
|
|
\begin{shell}
|
|
$\text{\$}$ sudo dpkg --install tools/linux/collada-dom2.2_2.2-1_amd64.deb tools/linux/collada-dom-dev_2.2-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 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}).
|
|
|
|
\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}
|
|
$\text{\$}$ yum install mercurial gcc-c++ scons boost-devel qt4-devel OpenEXR-devel xerces-c-devel
|
|
\end{shell}
|
|
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 here: \texttt{http://www.mitsuba-renderer.org/releases}.
|
|
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}).
|
|
|
|
\subsection{Building on Arch Linux}
|
|
There are two ways to install Mitsuba on Archlinux, the Arch way, and the other way.
|
|
|
|
The Arch Way is to use the Aur software repository.
|
|
Accessing software in the Aur repository is made a lot easier by using a script called packer.
|
|
|
|
First download packer then use makepkg to build and install it.
|
|
The -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.
|
|
\begin{shell}
|
|
$\text{\$}$ mkdir packer && cd packer
|
|
$\text{\$}$ wget http://aur.archlinux.org/packages/packer/packer/PKGBUILD
|
|
$\text{\$}$ makepkg -is
|
|
\end{shell}
|
|
|
|
Next use packer to automatically download, build, and install Mitsuba as well as any needed dependencies.
|
|
The optional --noedit flag is used if you do not wish to edit the files after they are downloaded.
|
|
The optional --noconfirm flag is used if you do not wish to confirm each step of the installation.
|
|
\begin{shell}
|
|
$\text{\$}$ sudo packer -S --noedit --noconfirm mitsuba-hg glewmx collada-dom
|
|
\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.
|
|
|
|
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}
|
|
This section assumes that Visual Studio 2008 is installed, but the instructions should work analogously for other versions.
|
|
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
|
|
(\url{www.python.org}) and 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 (it will complain about not finding a project file though).
|
|
\begin{shell}
|
|
C:\Users\Wenzel>scons
|
|
scons: ** No SConstruct file found.
|
|
\end{shell}
|
|
\emph{Note: }On some setups, 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.
|
|
Next, install Qt (\url{http://qt.nokia.com/downloads/windows-cpp-vs2008} -- you should get the release for Visual Studio 2008). Again, you need to make sure that the
|
|
Qt utilities are reachable through the \code{\%PATH\%} environment variable so that you can for example launch \code{moc.exe} from the command line.
|
|
|
|
Note that since the official release of Qt currently only contains 32-bit binaries, you will accordingly have to
|
|
build Mitsuba in 32-bit mode (i.e. you should use the configuration file \code{config-msvc2008-win32.py}). If you would rather like compile it in 64-bit mode,
|
|
you can either compile your own 64-bit Qt binaries or use the prebuilt
|
|
packages available here: \url{http://code.google.com/p/qt-msvc-installer}.
|
|
|
|
Having installed these dependencies, run the ``Visual Studio 2008 Command
|
|
Prompt'' from the Start Menu (\code{x86} for 32-bit or \code{x64} for 64bit). Afterwards,
|
|
navigate to the Mitsuba directory and run \code{scons}.
|
|
In the case that you have multiple processors, you might want to parallelize the build by appending \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 now located in the \code{dist} directory, and they should be executed directly from there.
|
|
\subsubsection{Integration with the Visual Studio interface}
|
|
If you plan to modify Mitsuba and you enjoy working within the Visual
|
|
Studio interface, the following steps should help you integrate the two
|
|
(thanks to Marios Papas for this description!). They are written for Visual Studio 2008,
|
|
hence some changes may be necessary on other versions. Also, they assume
|
|
that you followed all of the previous steps.
|
|
|
|
\begin{enumerate}
|
|
\item Create a copy of the file \code{config.py} in the Mitsuba root directory and
|
|
save it as \code{config\_debug.py}. This configuration
|
|
will later be used to support debug
|
|
builds. Open the file and make the following changes:
|
|
\begin{enumerate}
|
|
\item In \code{CXXFLAGS}, replace \code{/Ox} by \code{/Od} (this disables
|
|
optimizations, which is necessary to see variable contents in the debugger)
|
|
\item In \code{CXXFLAGS}, add an entry \code{'/Z7'}.
|
|
\item In \code{LINKFLAGS}, add an entry \code{'/DEBUG'}.
|
|
\end{enumerate}
|
|
\item Now, start a fresh instance of Visual Studio and click on
|
|
the \emph{File$\to$New$\to$Project From Existing Code} menu entry.
|
|
\item Choose \emph{Visual C++} from the drop-down menu and press \emph{Next}
|
|
\item Specify the Mitsuba root directory at the top and enter \emph{mitsuba}
|
|
as the project name.
|
|
|
|
In \emph{Add files to the project from these folders}, remove the Mitsuba
|
|
root directory and only add the \code{src} and \code{include} subdirectories.
|
|
This is crucial for IntelliSense to work.
|
|
Uncheck \emph{Show all files in Solution explorer} and
|
|
press \emph{Next}.
|
|
\item Choose \emph{Use external build system} and press \emph{Next}.
|
|
\item In the following, feel free to replace any occurrence of
|
|
\code{scons} by \code{scons -jX}, where \code{X} is the number of
|
|
cores in your machine (this will provide faster build times).
|
|
Fill in the following values:
|
|
|
|
\begin{tabular}{lp{9cm}}
|
|
\emph{Build command line}:&\code{scons {-}-cfg=config\_debug.py}\\
|
|
\emph{Rebuild command line}:&\code{scons {-}-cfg=config\_debug.py -c \&\& scons {-}-cfg=config\_debug.py}\\
|
|
\emph{Clean command line}:&\code{scons {-}-cfg=config\_debug.py -c}\\
|
|
\emph{Output}:&\code{dist\textbackslash mtsgui.exe}\\
|
|
\emph{Include search paths}:&\code{C:\textbackslash Qt\textbackslash
|
|
include} (or wherever the Qt headers are installed on your machine)
|
|
\end{tabular}
|
|
\item On the next page, uncheck \emph{Same as Debug configuration}.
|
|
Afterwards, enter exactly the same values as before except leaving out
|
|
the \code{{-}-cfg=config\_debug.py} parameter to \code{scons}.
|
|
\item Click \emph{Finish} and wait for IntelliSense to refresh (this might take
|
|
a while).
|
|
\item Switch to the Release configuration.
|
|
\end{enumerate}
|
|
\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}).
|