mingzailao
/
mitsuba
mirror of https://github.com/Quartenia/mitsuba.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Updated PDF manual's "Compiling the renderer" section (#37) 

* Replaced all URLs with the relevant GitHub ones
* Replaced Mercurial with Git
* Updated dependencies list
* Added qt5-default as the base package on Ubuntu to avoid QT_SELECT issues
* Updated MSVC references for VS 2017
* Updated MacOS instructions (wrt. COLLADA and Qt5)
* Added the `-parallelize` flag
* Specified that SCons 2.x is necessary
metadata
L. E. Segovia 2017-10-09 05:23:19 -03:00 committed by Wenzel Jakob
parent 463e09207b
commit 46650b73a1
1 changed files with 65 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

122
doc/compiling.tex
View File

@ -1,9 +1,9 @@
\section{Compiling the renderer} \section{Compiling the renderer}
\label{sec:compiling} \label{sec:compiling}
To compile Mitsuba, you will need a recent C++ compiler (e.g. GCC 4.2+ or To compile Mitsuba, you will need a recent C++ compiler (e.g. GCC 5.3+ or
Visual Studio 2010/2013) and some additional libraries, which Mitsuba uses internally. Visual Studio 2017) and some additional libraries, which Mitsuba uses internally.
Builds on all supported platforms are done using a unified system Builds on all supported platforms are done using a unified system
based on SCons (\url{http://www.scons.org}), which is a Python-based 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 software construction tool. The exact process is different depending on
which operating system is used and will be explained in the following subsections. which operating system is used and will be explained in the following subsections.
@ -15,13 +15,14 @@ license, the GPL automatically applies to derivative work. Amongst other things,
means that Mitsuba's source code is \emph{off-limits} to those who develop rendering means that Mitsuba's source code is \emph{off-limits} to those who develop rendering
software not distributed under a compatible license. software not distributed under a compatible license.
Check that the Mercurial (\url{http://mercurial.selenic.com/}) versioning Check that the Git (\url{https://git-scm.com/}) versioning system\footnote{On
system\footnote{On Windows, you might want to use the convenient TortoiseHG shell Windows, you might want to use the convenient TortoiseGit shell extension
extension (\url{http://tortoisehg.bitbucket.org/}) to run the subsequent steps directly from the Explorer.} (\url{https://tortoisegit.org/}) to run the subsequent steps directly from the
is installed, which is required to fetch the most recent source code release. Explorer.} is installed, which is required to fetch the most recent source code
Begin by entering the following at the command prompt (or run an equivalent command from a graphical Mercurial frontend): release.
Begin by entering the following at the command prompt (or run an equivalent command from a graphical Git frontend):
\begin{shell} \begin{shell}
$\texttt{\$}$ hg clone https://www.mitsuba-renderer.org/hg/mitsuba $\texttt{\$}$ git clone https://github.com/mitsuba-renderer/mitsuba
\end{shell} \end{shell}
This should dowload a full copy of the main repository. This should dowload a full copy of the main repository.
@ -36,25 +37,18 @@ On Linux, there are two supported configurations:
will run extremely slowly. Its main use is to track down elusive bugs. will run extremely slowly. Its main use is to track down elusive bugs.
\end{description} \end{description}
\paragraph{Windows:} \paragraph{Windows:}
On Windows, builds can either be performed using the Visual Studio 2010 or 2013\footnote{No other Visual Studio versions are currently supported.} On Windows, builds can be performed using the Visual Studio 2017\footnote{No other Visual Studio versions are currently supported.}
compiler or Intel XE Composer. compiler.
If you are using Visual Studio 2010, note that Service Pack 1 \emph{must} be installed or the resulting binaries will crash.
\begin{description} \begin{description}
\item[\code{build/config-\{win32, win64\}-\{msvc2010, msvc2010-debug\}.py}:] Create 32 or 64 bit binaries using Microsoft Visual C++ version 2010. \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. The configurations with the suffix \code{-debug} will include debug symbols in all binaries, which run very slowly.
\item[\code{build/config-win64-\{msvc2013, msvc2013-debug\}.py}:] Create 64 bit binaries using Microsoft Visual C++ version 2013. Please use
Visual Studio 2010 for legacy 32 bit builds.
\item[\code{build/config-\{win32, win64\}-icl.py}:] Create 32 or 64 bit release binaries using Intel XE Composer (on top of Visual Studio 2010).
Versions XE 2012 and 2013 are known to work.
\end{description} \end{description}
\paragraph{Mac OS:} \paragraph{Mac OS:}
On Mac OS, builds can either be performed using the XCode 4 \code{llvm-gcc} toolchain or Intel XE Composer. On Mac OS, builds can be performed using the XCode 8 \code{clang-llvm} toolchain.
It is possible to target MacOS 10.6 (Snow Leopard) or 10.7 (Lion) as the oldest supported operating system release. It is possible to target MacOS 10.12 (Sierra) as the oldest supported operating system release.
In both cases, XCode must be installed along with the supplementary command line tools. XCode must be installed along with the supplementary Command Line Tools.
\begin{description} \begin{description}
\item[\code{config-macos\{10.6, 10.7\}-gcc-\{x86,x86\_64,universal\}.py}:] Create Intel 32 bit, 64 bit, or universal binaries using the \code{llvm-gcc} toolchain. \item[\code{config-macos-10.12-clang-x86\_64.py}:] Creates 64-bit binaries using the \code{clang-llvm} toolchain.
\item[\code{config-macos\{10.6, 10.7\}-icl-\{x86,x86\_64\}.py}:] Create Intel 32 bit or 64 bit binaries using the Intel XE Composer toolchain.
Versions XE 2012 and 2013 are known to work.
\end{description} \end{description}
Note that the configuration files assume that XCode was Note that the configuration files assume that XCode was
installed in the \code{/Applications} folder. They must be manually updated installed in the \code{/Applications} folder. They must be manually updated
@ -104,27 +98,29 @@ as well as \code{MTS\_HAS\_COHERENT\_RT}.
\subsection{Building on Debian or Ubuntu Linux} \subsection{Building on Debian or Ubuntu Linux}
\label{sec:compiling-ubuntu} \label{sec:compiling-ubuntu}
You'll first need to install a number of dependencies. It is assumed here that you are using a You'll first need to install a number of dependencies. It is assumed here that you are using a
recent version of Ubuntu Linux (Precise Pangolin / 12.04 LTS or later), hence some of the 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. package may be named differently if you are using Debian Linux or another Ubuntu version.
First, run First, run
\begin{shell} \begin{shell}
$\text{\$}$ sudo apt-get install build-essential scons mercurial qt4-dev-tools libpng12-dev $\text{\$}$ sudo apt-get install build-essential scons git libpng12-dev
libjpeg-dev libilmbase-dev libxerces-c-dev libboost-all-dev libopenexr-dev libjpeg-dev libilmbase-dev libxerces-c-dev libboost-all-dev libopenexr-dev
libglewmx-dev libxxf86vm-dev libpcrecpp0 libeigen3-dev libfftw3-dev libglewmx-dev libxxf86vm-dev libeigen3-dev libfftw3-dev
\end{shell} \end{shell}
To get COLLADA support, you will also need to install the \texttt{collada-dom} packages 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 that can be found on the Mitsuba website (at \url{http://www.mitsuba-renderer.org/releases/current})
\begin{shell} \begin{shell}
$\text{\$}$ sudo dpkg --install collada-dom_*.deb $\text{\$}$ sudo apt-get install libcollada-dom-dev
\end{shell} \end{shell}
To start a regular build, run 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} \begin{shell}
$\text{\$}$ scons $\text{\$}$ scons
\end{shell} \end{shell}
inside the Mitsuba directory. In the case that you have multiple processors, you might want to parallelize the 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 \code{scons} command. 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: If all goes well, SCons should finish successfully within a few minutes:
\begin{shell} \begin{shell}
scons: $\texttt{done}$ building targets. scons: $\texttt{done}$ building targets.
@ -135,7 +131,7 @@ $\text{\$}$ source setpath.sh
\end{shell} \end{shell}
Having set up everything, you can now move on to \secref{basics}. Having set up everything, you can now move on to \secref{basics}.
\subsubsection{Creating Debian or Ubuntu Linux packages} \subsubsection{Creating Debian or Ubuntu Linux packages}
The preferred way of redistristributing executables on Debian or Ubuntu Linux is to create 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 \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 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 drivers ``pollute'' the OpenGL setup so that the compiled Mitsuba binaries
@ -159,7 +155,7 @@ $\text{\$}$ apt-get install debhelper dpkg-dev pkg-config
Now, you should be able to set up the remaining dependencies as described in \secref{compiling-ubuntu}. 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. Once this is done, check out a copy of Mitsuba to the root directory of the \code{chroot} environment, e.g.
\begin{shell} \begin{shell}
$\text{\$}$ hg clone https://www.mitsuba-renderer.org/hg/mitsuba $\text{\$}$ git clone https://github.com/mitsuba-renderer/mitsuba
\end{shell} \end{shell}
To start the compilation process, enter To start the compilation process, enter
\begin{shell} \begin{shell}
@ -191,12 +187,12 @@ 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). 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} \subsection{Building on Fedora Core}
You'll first need to install a number of dependencies. It is assumed here 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 that you are using FC27, hence some of the package may be named differently if you are
using another version. using another version.
First, run First, run
\begin{shell} \begin{shell}
$\text{\$}$ sudo yum install mercurial gcc-c++ scons boost-devel qt4-devel OpenEXR-devel xerces-c-devel python-devel glew-devel libpng-devel libjpeg-devel collada-dom-devel eigen3-devel fftw3-devel $\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} \end{shell}
Afterwards, simply run Afterwards, simply run
\begin{shell} \begin{shell}
@ -234,7 +230,7 @@ After this command finishes, its output can be found in the directory \code{rpmb
\subsection{Building on Arch Linux} \subsection{Building on Arch Linux}
You'll first need to install a number of dependencies: You'll first need to install a number of dependencies:
\begin{shell} \begin{shell}
$\text{\$}$ sudo pacman -S gcc xerces-c glew openexr boost libpng libjpeg qt scons mercurial python $\text{\$}$ sudo pacman -S gcc xerces-c glew openexr boost libpng libjpeg qt5 scons git python
\end{shell} \end{shell}
For COLLADA support, you will also have to install the \code{collada-dom} 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 library. For this, you can either install the binary package available on
@ -254,7 +250,7 @@ Once all dependencies are taken care of, simply run
\begin{shell} \begin{shell}
$\text{\$}$ scons $\text{\$}$ scons
\end{shell} \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. 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: If all goes well, SCons should finish successfully within a few minutes:
\begin{shell} \begin{shell}
scons: $\texttt{done}$ building targets. scons: $\texttt{done}$ building targets.
@ -281,42 +277,40 @@ $\text{\$}$ makepkg data/linux/arch/mitsuba/PKGBUILD
\subsection{Building on Windows} \subsection{Building on Windows}
Compiling Mitsuba's dependencies on Windows is a laborious process; for convenience, there 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 is a repository that provides them in precompiled form. To use this repository, clone it
using Mercurial and rename the directory so that it forms the \code{dependencies} subdirectory using Git and rename the directory so that it forms the \code{dependencies} subdirectory
inside the main Mitsuba directory, i.e. run something like inside the main Mitsuba directory, i.e. run something like
\begin{shell} \begin{shell}
C:\>cd mitsuba C:\>cd mitsuba
C:\mitsuba\>hg clone https://www.mitsuba-renderer.org/hg/dependencies_windows C:\mitsuba\>git clone https://github.com/mitsuba-renderer/dependencies_win64 dependencies
C:\mitsuba\>rename dependencies_windows dependencies
\end{shell} \end{shell}
There are a few other things that need to be set up: make sure that your 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 installation of Visual Studio is up to date, since Mitsuba binaries created with versions prior to 2017 will not link or crash.
prior to Service Pack 1 will crash.
Next, you will need to install Python 2.7.x 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 (\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 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.} 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\%} (\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}) environment variable so that entering \code{scons} on the command prompt (\code{cmd.exe})
launches the build system. launches the build system.
Having installed all dependencies, run the ``Visual Studio \emph{2010} Command Having installed all dependencies, run the ``x64 Native Tools Command Prompt
Prompt'' from the Start Menu (\code{x86} for 32-bit or \code{x64} for 64bit), for VS \emph{2017}'' from the Start Menu,
navigate to the Mitsuba directory, and simply run navigate to the Mitsuba directory, and simply run
\begin{shell} \begin{shell}
C:\mitsuba\>scons C:\mitsuba\>scons
\end{shell} \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. 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 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. 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. 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} \subsubsection{Integration with the Visual Studio interface}
Basic Visual Studio 2010 integration with support for code completion Basic Visual Studio 2017 integration with support for code completion
exists for those who develop Mitsuba code on Windows. 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-msvc2010.sln} To use the supplied projects, simply double-click on one of the two files \code{build/mitsuba-msvc2017.sln}
and \code{build/mitsuba-msvc2010.sln}. These Visual Studio projects still internally and \code{build/mitsuba-msvc2017.vcxproj}. These Visual Studio projects still internally
use the SCons-based build system to compile Mitsuba; whatever use the SCons-based build system to compile Mitsuba; whatever
build configuration is selected within Visual Studio will be used to pick a matching build configuration is selected within Visual Studio will be used to pick a matching
configuration file from the \texttt{build} directory. configuration file from the \texttt{build} directory.
@ -325,25 +319,40 @@ configuration file from the \texttt{build} directory.
\vspace{-5mm} \vspace{-5mm}
\remarks{ \remarks{
\item Unfortunately, OpenMP is not available when compiling \item Unfortunately, OpenMP is not available when compiling
using the regular \code{clang} toolchain (it is available when using Intel XE Composer). This will cause the following parts of Mitsuba using the regular \code{clang} toolchain.
to run single-threaded: bitmap resampling (i.e. MIP map generation), blue noise point generation in the \pluginref{dipole} 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. 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 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 is a repository that provides them in precompiled form. To use this repository, clone it
using Mercurial and rename the directory so that it forms the \code{dependencies} subdirectory using Git and rename the directory so that it forms the \code{dependencies} subdirectory
inside the main Mitsuba directory, i.e. run something like inside the main Mitsuba directory, i.e. run something like
\begin{shell} \begin{shell}
$\text{\$}$ cd mitsuba $\text{\$}$ cd mitsuba
$\text{\$}$ hg clone https://www.mitsuba-renderer.org/hg/dependencies_macos $\text{\$}$ git clone https://github.com/mitsuba-renderer/dependencies_macos dependencies
$\text{\$}$ mv dependencies_macos dependencies
\end{shell} \end{shell}
You will also need to install SCons (>2.0.0, available at \code{www.scons.org}) and 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 a recent release of XCode, including its command-line compilation tools. Next, run
\begin{shell} \begin{shell}
$\text{\$}$ scons $\text{\$}$ scons
\end{shell} \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. 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: If all goes well, SCons should finish successfully within a few minutes:
\begin{shell} \begin{shell}
scons: $\texttt{done}$ building targets. scons: $\texttt{done}$ building targets.
@ -352,4 +361,3 @@ To run the renderer from the command line, you first have to import it into your
\begin{shell} \begin{shell}
$\text{\$}$ source setpath.sh $\text{\$}$ source setpath.sh
\end{shell} \end{shell}