If you have problems with the compilation, please ask on the appropriate
RawTherapee forum: http://www.rawtherapee.com/forum/viewforum.php?f=10

PREAMBLE
--------

  Some commands span multiple lines, each line of such a command except for the
  last one will end in a backslash character, "\".
  When copying code, be sure to copy all lines from the first one that ends in \
  till the last line that does not end in a \ character.

  Some parts of code contain <variable containers>. Replace these with whatever
  value is needed, e.g. <your favorite drink>

  CMake is actually used to create the makefiles (scripts that handle the build
  process) or specific Integrated Developement Environement (IDE) projects.  It
  is designed to find all necessary compilation flags for your specific machine,
  but everything can be overriden.

  RawTherapee's build mechanism will generate a build information file, named
  "AboutThisBuild.txt", and require some parameters that can't be set by CMake,
  so it's done in our build script, and may be overridden at your own will. The
  build process also enables some sort of cross-compiling, since you can only
  choose a specific processor variation of the same type (e.g. core2, athlon64,
  which are both an x86 architecture). Real cross-compiling (e.g. building the
  Windows version on a Linux platform) has not been tested.

  By default, no processor is specified, so CMake/GCC will build RT for your
  machine's processor. You can specify that the build is to be made for a
  generic processor by using the -DPROC_TARGET_NUMBER="1" CMake option.
  Developers who are providing builds for download from the RawTherapee website
  have to set the processor label (a human-readable description of the
  processor, set to "undefined" by default) manually with the -DPROC_LABEL="foo"
  CMake parameter.

  Note for developers that handle an automated build system: Mercurial is
  required in order to produce the build information file, but your build system
  will certainly only use the source code without any access to a Mercurial
  repository. To generate the needed information, run the script:
    ./tools/generateReleaseInfo
  After that, you can delete .hg* (the example below uses "-X *.hg*" to exclude
  those files and folders instead of deleting them - the end result is the same)
  and continue with the normal compile instructions without the need for
  mercurial.

  In short, once you cd into your clone of the RawTherapee source code
  repository, using version "4.1" as an example:
  1. Check out the desired hg tag: hg update "4.1"
  2. Run tools/generateReleaseInfo to generate ReleaseInfo.cmake:
      ./tools/generateReleaseInfo
  3. The repository is now ready to be made into a public tarball:
      ./tools/generateSourceTarball

  The build system especially encourages to perform out-of-source builds. This
  means that the CMake project is generated in a folder which is not in the
  source tree of RawTherapee. This way the source tree stays clean all the time
  and multiple different compilation settings can be maintained in parallel
  using different binary folders. Further information about out-of-source builds
  can be found here:
    http://www.cmake.org/Wiki/CMake_FAQ#What_is_an_.22out-of-source.22_build.3F

  If an in-source build is performed, the CMake logic now warns about this but
  does not fail. Especially important for clean out-of-source builds is that the
  CMake code does not generate files inside the source tree, e.g. when using
  configure_file. Please keep this in mind when altering the CMake files.


DEPENDENCIES
------------

  PACKAGE                        URL
  BZIP2       bzip2>-1.0.4       http://www.bzip.org/
  EXIV2       exiv2>=0.19        http://www.exiv2.org/
  EXPAT       expat>=2.1.0       http://expat.sourceforge.net/
  FFTW        fftw>=3.2.2        http://fftw.org/
  GCC         gcc>=4.7           http://gcc.gnu.org/
  GLIB2       glib-2.0>=2.24     http://www.gtk.org/
  GLIBMM      glibmm-2.4>=2.24   http://www.gtkmm.org
  GTK+        gtk+-2.0>=2.24.18  http://www.gtk.org/
  GTKMM       gtkmm-2.4>=2.22    http://www.gtkmm.org
  JPEG        libjpeg>=6b        http://libjpeg-turbo.virtualgl.org/
                                 http://jpegclub.org/
                                 http://www.ijg.org/
  LIBCANBERRA libcanberra-gtk    http://0pointer.de/lennart/projects/libcanberra/ (Linux only)
  LCMS2       lcms>=2.0a         http://www.littlecms.com/
  LIBIPTCDATA libiptcdata>=1.0.2 http://libiptcdata.sourceforge.net
  PNG         libpng>=1.2.44     http://www.libpng.org/
  SIGC        sigc++-2.0         http://libsigc.sourceforge.net/
  TIFF        libtiff>=3.9.4     http://www.remotesensing.org/libtiff/
  ZLIB        zlib>=1.2.3-r1     http://www.zlib.net/


WINDOWS
-------

  OPTIONAL

    - TortoiseHG
      You can make your life a little easier by using a graphical client for
      working with Mercurial. One such free and open-soure cross-platform
      client is TortoiseHG, you can get it bundled with Mercurial from:
        http://tortoisehg.bitbucket.org/

    - Weird compressed archive formats?
      You might need to unpack archives in formats which Windows does not
      handle by default. That's no problem, there are a few free programs out
      there which handle many more formats than Windows does, and faster too.
      We recommend:
        http://www.7-zip.org/
        http://peazip.sourceforge.net/


  THE TOOLCHAIN

    This document assumes that you install MinGW, CMake and gtkmm respectively
    to "C:\MinGW64" (or "C:\MinGW32" for 32-bit), "C:\CMake", and "C:\gtkmm64" (or
    "C:\gtkmm" for 32-bit).
    These packages must be installed in paths that DO NOT CONTAIN SPACES.

    INSTALL THE TOOLCHAIN
      - TDM-GCC On-Demand Installer
          http://tdm-gcc.tdragon.net/download
        GCC 4.7 is recommended, as under some conditions older
        versions of GCC can cause artifacts.
        Download the "tdm-gcc-webdl" option. Run it, select "Create a new
        TDM-GCC installation" and choose the appropriate option for your
        machine: "MinGW/TDM (32-bit)" if you use a 32-bit machine, or
        "MinGW-w64/TDM64 Experimental (32-bit and 64-bit)" if you use a 64-bit
        machine. Even though the 64-bit version contains a 32-bit version too,
        we had no luck making 32-bit RT builds using it at the time of writing.
        Be sure to install with OpenMP support (Components > gcc > openmp).

      - CMake
          http://www.cmake.org/cmake/resources/software.html
        Use "Windows (Win32 Installer)", the newest version.
        
      - >=GTK+ 2.24.18
          http://hexchat.github.io/gtk-win32/

      - gtkmm-2.24
          http://sourceforge.net/projects/gtk-mingw/files/gtkmm2/


    INSTALL THE DEPENDENCIES

      RawTherapee depends on additional build-time libraries. There are two ways
      you can get these libraries:
        - The easy way, you can use the pre-compiled ones available from:
            http://www.rawtherapee.com/releases_head/windows/dependencies_for_creating_builds/
          Just unzip them to the base installation dir of MinGW, which should be
          C:\MinGW64 if you followed the instructions to the letter.

          Note that this archive might not contain all of the required
          libraries. If compilation fails due to missing libraries, then see the
          dependency list at the beginning of this document, find the missing
          ones, and see below for instructions on where to download them from
          and how to install them. Please notify us so that we may update the
          archive.

        - The hard way, you will need to download the source code for each and
          compile each yourself. See further below for instructions.


    SET UP THE TOOLCHAIN ENVIRONMENT VARIABLES

      The toolchain installers should have set up some environment variables
      for you automatically, but some will be missing. Fire up:
        System Properties > Advanced > Environment Variables

      Make sure you have the relevant ones, and that they point to the correct
      places:
        GTKMM_BASEPATH = "C:\gtkmm"
        GTKMM64_BASEPATH = "C:\gtkmm64"
        MINGW_BASEPATH = "C:\MinGW64"
        PKG_CONFIG_PATH = "C:\MinGW64\lib\pkgconfig;c:\gtkmm64\lib\pkgconfig"
        and that PATH contains "C:\gtkmm64\bin;C:\MinGW64\bin;C:\CMake\bin;"
        (or the 32-bit counteparts)

      Restart your console to be sure the changes took effect.


  COMPILE
    - Clone or update the RawTherapee repository
        You can use TortoiseHG to clone and update the repository, or you can
        do it from the command line:
          hg clone https://rawtherapee.googlecode.com/hg/ "C:\rtrepo"
        If you have already cloned it before, update it:
          cd C:\rtrepo
          hg pull
          hg update -C default

    - Tailor the buildRT.bat batch file to your needs
        Copy C:\rtrepo\tools\buildRT.bat to C:\buildRT.bat so that you can make
        changes to it and not lose them when you update the repository.

        Edit C:\buildRT.bat and customize as follows:
          - If you are building RT for yourself, use
            "-DPROC_TARGET_NUMBER:STRING=2"
          - If you are building RT to be distributed to other people, use
            "-DPROC_TARGET_NUMBER:STRING=1"
          - If you want to upload a build, you should set some additional
            information about your processor. There are two possibilities:
            1. You pick up a target processor from "ProcessorTargets.cmake".
               All you have to do is set the PROC_TARGET_NUMBER parameter
               to the desired target number.  If you choose the "native"
               solution, you have to set the processor label manually
               by setting the PROC_LABEL parameter. Please provide a short name,
               like "core i5" or "athlon64". Processor frequency is of no use.
            2. You don't need specific processor flags, so you'll let
               PROC_TARGET_NUMBER default to 0, but you have to set the
               PROC_LABEL parameter. Please provide a short name, like "core i5"
               or "athlon64". Specifying the processor frequency is of no use.

    - Run buildRT.bat to compile RawTherapee
        C:\buildRT.bat


  DEPENDENCIES - THE HARD WAY

    The MSYS package is required to build the libraries. Before building them,
    check if they are already installed in your gtkmm and MinGW directories.
    There shouldn't be two versions of the same library in different places.

      Open an MSYS console, that will create a Linux environment, and compile
      the dependencies in the following order:
        zlib:
          If you have gtkmm-2.22 installed, you should skip this zlib section.
          - Download: http://zlib.net/
          - How to build:
              cd to the directory you unpacked zlib-1.2.5 to,
              make -f win32/Makefile.gcc

          Then, manually copy the files as follows (tip: you can individually
          copy the lines below and paste them in MSYS' prompt with the middle
          mouse button):
          cp -iv zlib1.dll /mingw/bin
          cp -iv zconf.h zlib.h /mingw/include
          cp -iv libz.a /mingw/lib
          cp -iv libzdll.a /mingw/lib/libz.dll.a

        libpng:
          If you have gtkmm-2.22 installed, you should skip this libpng section.
          - Download: http://sourceforge.net/projects/libpng/files/
          - How to build:
            cd to the directory you unpacked lpng144 to.
            There are two methods of building libpng:
              1. gtkmm doesn't provide zlib so compile it yourself:
                  cmake -G "MSYS Makefiles" -DCMAKE_INSTALL_PREFIX:PATH=/mingw -DCMAKE_BUILD_TYPE:STRING=Release
              2. gtkmm provides zlib so you can reuse it (assuming that you
                 hadn't compiled zlib as explained above):
                  cmake -G "MSYS Makefiles" -DCMAKE_INSTALL_PREFIX:PATH=/mingw -DCMAKE_PREFIX_PATH:PATH=C:/gtkmm -DCMAKE_BUILD_TYPE:STRING=Release

              Then build and install:
                make
                make install

        libjpeg:
          - Download: http://www.ijg.org/
          - How to build:
              cd to the directory you unpacked jpeg-8b to.
              ./configure --prefix=/mingw
              Copy jconfig.txt to jconfig.h (overwrite the existing file).
              make
              make install

        libtiff:
          - Download: ftp://ftp.remotesensing.org/pub/libtiff/
          - How to build:
            In the configure process below, set the zlib include and lib path to
            the right folder. We're assuming that you're using the one provided
            in the gtkmm bundle.
              ./configure --prefix=/mingw --with-zlib-include-dir=/c/gtkmm/include --with-zlib-lib-dir=/c/gtkmm/lib
              make
              cd libtiff
              make install

        libiptcdata:
          - Download: http://libiptcdata.sourceforge.net/
          - How to build:
              ./configure --prefix=/mingw

              Edit the "Makefile" file from the root dir of libiptcdata and
              search for "DIST_SUBDIRS =" and "SUBDIRS =". You should only find
              one line for each search. From these lines, remove "iptc", then:
              make
              make install

        LCMS:
          - Download LCMS2
              http://sourceforge.net/projects/lcms/files/
          - How to build:
              ./configure --prefix=/mingw
              make
              make install

        Expat:
          - Download: http://expat.sourceforge.net/
          - Install

        FFTW:
          - Instructions: http://www.fftw.org/install/windows.html
          - Specific instructions more suitable for RawTherapee purposes:
            1. Download the official FFTW-64 DLL package from
                http://www.fftw.org/download.html
               Unpack it to C:\fftw3\
            2. Start MSYS console and go to your FFTW3 directory
                cd /c/fftw3
            2. In MSYS console, execute:
                dlltool --def libfftw3f-3.def --dllname libfftw3f-3.dll --output-lib libfftw3f-3.a
                dlltool --def libfftw3l-3.def --dllname libfftw3l-3.dll --output-lib libfftw3l-3.a
                dlltool --def libfftw3-3.def --dllname libfftw3-3.dll --output-lib libfftw3-3.a
            3. Copy files:
                cp libfftw3f-3.dll /c/MinGW64/bin
                cp libfftw3l-3.dll /c/MinGW64/bin
                cp libfftw3-3.dll /c/MinGW64/bin
                cp libfftw3f-3.a /c/MinGW64/lib
                cp fftw3.h /c/MinGW64/include
            4. Create a new text file MinGW64/lib/pkgconfig/fftw3f.pc with the
               following contents:
                prefix=/mingw64
                exec_prefix=${prefix}
                libdir=${exec_prefix}/lib
                includedir=${prefix}/include
                Name: fftw3f
                Description: FFTW3 Float
                Version: 3.3
                Libs: -L${libdir} -lfftw3f-3 -lm
                Cflags: -I${includedir}


      IMPORTANT

        Make sure that the lcms.pc and libiptcdata.pc files located in the
        pkgconfig dir have the first line like this:
          prefix=/mingw

        If everything has been installed correctly, you should see lines like
        the following when running the cmake command (see "COMPILE" below):
          -- checking for module 'libiptcdata'
          --   found libiptcdata, version 1.0.4
          -- checking for module 'lcms2'
          --   found lcms2, version 2.3
          -- Found JPEG: C:/mingw/lib/libjpeg.dll.a
          -- Found ZLIB: C:/gtkmm/lib/libz.dll.a
          -- Found PNG: C:/gtkmm/lib/libpng.lib
          -- Found TIFF: C:/mingw/lib/libtiff.dll.a


LINUX
-----

  DEPENDENCIES

    See the list of dependencies at the beginning of this document.

    In Arch, run:
      sudo pacman -S bzip2 exiv2 expat fftw glib2 glibmm gtk gtkmm lcms2       \
      libcanberra libiptcdata libjpeg-turbo libpng libsigc++ libtiff zlib

    In Fedora, run:
      sudo yum install bzip2-devel cmake exiv2-devel expat-devel fftw-devel    \
      gcc-c++ glib2-devel glibmm24-devel gtk+-devel gtkmm24-devel lcms2-devel  \
      libcanberra-devel libiptcdata-devel libjpeg-turbo-devel libpng-devel     \
      libsigc++20-devel libtiff-devel zlib-devel

    In Gentoo, run:
      sudo emerge -uva app-arch/bzip2 dev-cpp/glibmm dev-cpp/gtkmm             \
      dev-libs/expat dev-libs/glib dev-libs/libsigc++ dev-vcs/mercurial        \
      media-gfx/exiv2 media-libs/lcms media-libs/libcanberra                   \
      media-libs/libiptcdata media-libs/libjpeg-turbo media-libs/libpng        \
      media-libs/tiff net-misc/curl sci-libs/fftw sys-libs/zlib x11-libs/gtk+

    In openSUSE, run:
      sudo zypper in cmake fftw3-devel gcc-c++ glib2-devel glibmm2-devel       \
      gtk2-devel gtkmm2-devel libbz2-devel libcanberra-devel libexpat-devel    \
      libiptcdata-devel libjpeg-devel liblcms2-devel libpng-devel              \
      libsigc++2-devel libtiff-devel zlib-devel

    In Ubuntu/Debian the requirements can be installed by running:
      sudo apt-get update && sudo apt-get install build-essential cmake curl   \
      libbz2-dev libcanberra-gtk-dev libexiv2-dev libexpat-dev libfftw3-dev    \
      libglibmm-2.4-dev libgtk2.0-dev libgtkmm-2.4-dev libiptcdata0-dev        \
      libjpeg8-dev liblcms2-dev libpng12-dev libsigc++-2.0-dev libtiff4-dev    \
      mercurial zlib1g-dev


  COMPILE

    The Automatic Way:
      The easiest way compile RawTherapee is by using the buildRT script, read
      all about it in the forum:
        http://rawtherapee.com/forum/viewtopic.php?p=22213#p22213

    The Manual Way:
      - Create and enter a new empty folder outside RawTherapee's source
        directory:
          mkdir ~/rt-build
          cd ~/rt-build
      - Type:
          cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=./release \
          -DBINDIR=. -DDATADIR=. -DLIBDIR=. <path to source directory>
        Developers who want to provide a public build have to set the PROC_LABEL
        to their processor name, e.g.:
          cmake -DPROC_LABEL:STRING=athlon64 -DCMAKE_BUILD_TYPE=Release \
          -DCMAKE_INSTALL_PREFIX=./release -DBINDIR=. -DDATADIR=. -DLIBDIR=. \
          <path to source directory>
      - Type:
          make install
      - You'll find the compiled program in the subdirectory named like the
        value of CMAKE_BUILD_TYPE ("Release" in this example). You can copy it
        anywhere you want. By changing the cmake flags, you can change where
        the release will compile to. By removing all flags it should go to the
        standard system install location.

    You're done.


  Using Eclipse under Linux:

    Eclipse mercurial plugin: Click "Help > Install New Software".
    The Eclipse Update Site for MercurialEclipse is available at this URL:
    http://cbes.javaforge.com/update

    Import the RawTherapee Mercurial repository:
      "File > new > other > mercurial > Clone existing repository"
    Enter this URL:
      https://rawtherapee.googlecode.com/hg

    Create and enter a new empty folder outside RawTherapee's source directory.
    Configure the source for Eclipse with:
      cmake -G "Eclipse CDT4 - Unix Makefiles" -DCMAKE_INSTALL_PREFIX=./release -DBINDIR=. -DDATADIR=. -DLIBDIR=. -DCMAKE_BUILD_TYPE=Release <path to source directory>

    If you want to upload a build, you should set some additional information
    about your processor. There are two possibilities:
      1. You pick up a target processor from "ProcessorTargets.cmake". All you
         have to do is set "-D PROC_TARGET_NUMBER:STRING=number" in cmake's
         command line to the desired target number. If you choose the 'native'
         solution, you have to set the processor label manually by setting "-D
         PROC_LABEL:STRING=procLabel" in cmake's command line. Please provide a
         short name, like "core i5" or "athlon64" (without double quotes).
         Processor frequency is of no use.
      2. You don't need specific processor flags, so you'll let
         PROC_TARGET_NUMBER default to 0, but you still have to set the
         PROC_LABEL parameter (see point 1 righ above).

    Eclipse does not do 'make install', but only 'make all'.
    There are two ways to compile:
      1. type 'make install' in the console or,
      2. in "Project > properties > C/C++ Make Project > Build (incremental
         build)" change 'all' to 'install'.

OS X
----

  REQUIREMENTS

    - XCode Development Tools (you only need a subset of these, but it is
      probably easier to just install all of them)
    - MacPorts
      - To install the dependencies, run:
          sudo port install cairo +quartz -x11 pango +quartz -x11 gdk-pixbuf2 -x11 gtk2 +quartz libsigcxx2 gtk-osx-application +no_python
      - gtkmm port will fail to install. Use `-s’ option.
          sudo port -s install gtkmm
      - To install other dependencies and tools.
          sudo port install gtk-engines2 lcms2 libiptcdata fftw-3-single cmake gcc47
      - If you don't already have Mercurial installed, run:
          sudo port install mercurial


  COMPILE

    - Make build directory.
        mkdir build
        cd build
    - To enable OpenMP, assuming you have installed gcc47), type:
        cmake -D CMAKE_C_COMPILER=gcc-mp-4.7 -D CMAKE_CXX_COMPILER=g++-mp-4.7 \
        <path to source directory>

    If you want to upload a build, you should set some additional information
    about your processor. There are two possibilities:
      1. You pick up a target processor from "ProcessorTargets.cmake". All you
         have to do is set "-D PROC_TARGET_NUMBER:STRING=number" in cmake's
         command line to the desired target number. If you choose the 'native'
         solution, you have to set the processor label manually by setting "-D
         PROC_LABEL:STRING=procLabel" in cmake's command line. Please provide a
         short name, like "core i5" or "athlon64" (without double quotes).
         Processor frequency is of no use.
      2. You don't need specific processor flags, so you'll let
         PROC_TARGET_NUMBER default to 0, but you still have to set the
         PROC_LABEL parameter (see point 1 righ above).

    - Type:
        make install
    - Type:
        make macosx_bundle
    - You will find a disk image in the build directory; this is the
      distribution release and can be run on any machine which meets the
      architecture requirements you specified in variants.conf earlier.
