272 lines
14 KiB
TeX
272 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 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 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\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 the
|
|
subdirectory \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}
|
|
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}
|
|
|
|
Usually, you will not have to make any modification to this fine, 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 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 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.
|
|
\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},
|
|
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}
|
|
$\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 available on the Mitsuba website:
|
|
\begin{shell}
|
|
$\text{\$}$ sudo dpkg --install collada-dom2.2_2.2-2_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}).
|
|
|
|
\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}
|
|
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\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.$x$ (where $x\ge 7$) from source or grab pre-built binaries from the following page: \url{http://code.google.com/p/qt-msvc-installer}. It is crucial that the build configuration is identical: for instance, when you are compiling Mitsuba using the 64-bit compiler in Visual Studio 2010, you will need Qt binaries made with that same compiler. When compiling Qt from source,
|
|
start the correct Visual Studio command prompt, and 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}
|
|
inside the Qt directory.
|
|
|
|
Having installed these 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 and run \code{scons}.
|
|
Depending on whether or not the Qt binaries are on the \code{\%PATH\%}
|
|
environment variable, you may also have to enter
|
|
\begin{shell}
|
|
set QTDIR=C:\Qt
|
|
\end{shell}
|
|
where \code{C:$\backslash$Qt} is the path to your Qt installation.
|
|
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}).
|