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

doc/compiling.tex

@@ -1,9 +1,9 @@
 \section{Compiling the renderer}
 \label{sec:compiling}
-To compile Mitsuba, you will need a recent C++ compiler (e.g. GCC 4.2+ or
-Visual Studio 2010/2013) and some additional libraries, which Mitsuba uses internally.
+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 (\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
 which operating system is used and will be explained in the following subsections.
 
@@ -15,13 +15,14 @@ \subsection{Common steps}
 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 Mercurial (\url{http://mercurial.selenic.com/}) versioning
-system\footnote{On Windows, you might want to use the convenient TortoiseHG shell
-extension (\url{http://tortoisehg.bitbucket.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 Mercurial frontend):
+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{\$}$ hg clone https://www.mitsuba-renderer.org/hg/mitsuba
+$\texttt{\$}$ git clone https://github.com/mitsuba-renderer/mitsuba
 \end{shell}
 This should dowload a full copy of the main repository.
 
@@ -36,25 +37,18 @@ \subsubsection{Build configurations}
 will run extremely slowly. Its main use is to track down elusive bugs.
 \end{description}
 \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.}
-compiler or Intel XE Composer.
-If you are using Visual Studio 2010, note that Service Pack 1 \emph{must} be installed or the resulting binaries will crash.
+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-\{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.
-\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}
 \paragraph{Mac OS:}
-On Mac OS, builds can either be performed using the XCode 4 \code{llvm-gcc} toolchain or Intel XE Composer.
-It is possible to target MacOS 10.6 (Snow Leopard) or 10.7 (Lion) as the oldest supported operating system release.
-In both cases, XCode must be installed along with the supplementary command line tools.
+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.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.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.
+\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
@@ -104,27 +98,29 @@ \subsection{Compilation flags}
 \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 (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.
 
 First, run
 \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
-    libglewmx-dev libxxf86vm-dev libpcrecpp0 libeigen3-dev libfftw3-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
-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})
+To get COLLADA support, you will also need to install the \texttt{collada-dom} packages:
 \begin{shell}
-$\text{\$}$ sudo dpkg --install collada-dom_*.deb
+$\text{\$}$ sudo apt-get install libcollada-dom-dev
 \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}
 $\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 \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:
 \begin{shell}
 scons: $\texttt{done}$ building targets.
@@ -135,7 +131,7 @@ \subsection{Building on Debian or Ubuntu Linux}
 \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 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
 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
@@ -159,7 +155,7 @@ \subsubsection{Creating Debian or Ubuntu Linux packages}
 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{\$}$ hg clone https://www.mitsuba-renderer.org/hg/mitsuba
+$\text{\$}$ git clone https://github.com/mitsuba-renderer/mitsuba
 \end{shell}
 To start the compilation process, enter
 \begin{shell}
@@ -191,12 +187,12 @@ \subsubsection{Releasing Ubuntu packages}
 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 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.
 
 First, run
 \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}
 Afterwards, simply run
 \begin{shell}
@@ -234,7 +230,7 @@ \subsubsection{Creating Fedora Core packages}
 \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 qt scons mercurial python
+$\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
@@ -254,7 +250,7 @@ \subsection{Building on Arch Linux}
 \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.
+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.
@@ -281,42 +277,40 @@ \subsubsection{Creating Arch Linux packages}
 \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 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
 \begin{shell}
 C:\>cd mitsuba
-C:\mitsuba\>hg clone https://www.mitsuba-renderer.org/hg/dependencies_windows
-C:\mitsuba\>rename dependencies_windows dependencies
+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 Service Pack 1 will crash.
+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.}
+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 ``Visual Studio \emph{2010} Command
-Prompt'' from the Start Menu (\code{x86} for 32-bit or \code{x64} for 64bit),
+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} 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
 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 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.
-To use the supplied projects, simply double-click on one of the two files \code{build/mitsuba-msvc2010.sln}
-and \code{build/mitsuba-msvc2010.sln}. These Visual Studio projects still internally
+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.
@@ -325,25 +319,40 @@ \subsection{Building on Mac OS X}
 \vspace{-5mm}
 \remarks{
     \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
-    to run single-threaded: bitmap resampling (i.e. MIP map generation), blue noise point generation in the \pluginref{dipole}
+    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 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
 \begin{shell}
 $\text{\$}$ cd mitsuba
-$\text{\$}$ hg clone https://www.mitsuba-renderer.org/hg/dependencies_macos
-$\text{\$}$ mv dependencies_macos dependencies
+$\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} 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:
 \begin{shell}
 scons: $\texttt{done}$ building targets.
@@ -352,4 +361,3 @@ \subsection{Building on Mac OS X}
 \begin{shell}
 $\text{\$}$ source setpath.sh
 \end{shell}
-