doc/build_systems/cmake.txt

   1
   2     Blender CMake build system
   3     ============================
   4
   5     Contents
   6     ---------------
   7
   8     1. Introduction
   9     2. Obtaining CMake
  10     3. Obtaining Dependencies
  11     4. Deciding on a Build Environment
  12     5. Configuring the build for the first time
  13     6. Configuring the build after SVN updates
  14     7. Specify alternate Python library versions and locations
  15
  16
  17     1. Introduction
  18     ---------------
  19
  20     This document describes general usage of the new CMake scripts. The
  21     inner workings will be described in blender-cmake-dev.txt (TODO).
  22
  23     2. Obtaining CMake
  24     ------------------
  25
  26     CMake for can either be downloaded using your favorite package manager
  27     or is also available from the CMake website at http://www.cmake.org
  28     The website also contains some documentation on CMake usage but I found
  29     the man page alone pretty helpful.
  30
  31     3. Obtaining Dependencies
  32     -------------------------
  33
  34     Check from the page
  35     http://www.blender.org/cms/Getting_Dependencies.135.0.html that you
  36     have all dependencies needed for building Blender. Note that for
  37     windows many of these dependencies already come in the lib/windows
  38     module from SVN.
  39
  40     4. Deciding on a Build Environment
  41     ----------------------------------
  42
  43     To build Blender with the CMake scripts you first need to decide which
  44     build environment you feel comfortable with. This decision will also be
  45     influenced by the platform you are developing on. The current implementation
  46     have been successfully used to generate build files for the following
  47     environments:
  48
  49     1. Microsoft Visual Studio 2008. There is a free version available
  50        at http://http://www.microsoft.com/visualstudio/en-us/products/2008-editions/express
  51
  52     2. Xcode on Mac OSX
  53
  54     3. Unix Makefiles (On Linux and Mac OSX): CMake actually creates make
  55        files which generates nicely color coded output and a percentage
  56        progress indicator.
  57
  58
  59     5. Configuring the build for the first time
  60     -------------------------------------------
  61
  62     CMake allows one to generate the build project files and binary objects
  63     outside the source tree which can be pretty handy in working and experimenting
  64     with different Blender configurations (Audio/NoAudio, GameEngine/NoGameEngine etc.)
  65     while maintaining a clean source tree. It also makes it possible to generate files
  66     for different build systems on the same source tree. This also has benefits for
  67     general SVN management for the developer as patches and submit logs are much cleaner.
  68
  69     Create a directory outside the blender source tree where you would like to build
  70     Blender (from now on called $BLENDERBUILD). On the commandline you can then run
  71     the cmake command to generate your initial build files. First just run 'cmake' which
  72     will inform you what the available generators are. Thn you can run
  73     'cmake -G generator $BLENDERSOURCE' to generate the build files. Here is an example
  74     of all this for Xcode:
  75
  76         % mkdir $BLENDERBUILD
  77         % cd $BLENDERBUILD
  78         % cmake
  79
  80         ...
  81         ...
  82         --version [file]            = Show program name/version banner and exit.
  83
  84         Generators
  85
  86         The following generators are available on this platform:
  87           KDevelop3                   = Generates KDevelop 3 project files.
  88           Unix Makefiles              = Generates standard UNIX makefiles.
  89           Xcode                       = Generate XCode project files.
  90
  91
  92
  93         % cmake -G Xcode $BLENDERSOURCE
  94         ...
  95         ...
  96         -- Configuring blender
  97         -- Configuring blenderplayer
  98         -- Configuring done
  99         -- Generating done
 100         -- Build files have been written to: $BLENDERBUILD
 101
 102     This will generate the build files with default values. Specific features can
 103     be enabled or disabled by running the ccmake "GUI" from $BLENDERBUILD as follows:
 104
 105         % ccmake $BLENDERSOURCE
 106
 107     A number of options appear which can be changed depending on your needs and
 108     available dependencies (e.g. setting WITH_OPENEXR to OFF will disable support
 109     for OpenEXR). It will also allow you to override default and detected paths
 110     (e.g. Python directories) and compile and link flags. When you are satisfied
 111     used ccmake to re-configure the build files and exit.
 112
 113     It is also possible to use the commandline of 'cmake' to override certain
 114     of these settings.
 115
 116     6. Configuring the build after SVN updates
 117     ------------------------------------------
 118
 119     The $BLENDERBUILD directory maintains a file called CMakeCache.txt which
 120     remembers the initial run's settings for subsequent generation runs. After
 121     every SVN update it may be a good idea to rerun the generation before building
 122     Blender again. Just rerun the original 'cmake' run to do this, the settings
 123     will be remembered. For the example above the following will do after every
 124     'svn up':
 125
 126         % cmake -G Xcode $BLENDERSOURCE
 127
 128     7. Specify alternate Python library versions and locations
 129     ----------------------------------------------------------
 130
 131     The commandline can be used to override detected/default settings, e.g:
 132
 133     On Unix:
 134       cmake -D PYTHON_LIBRARY=/usr/local/lib/python3.2/config/libpython3.2.so -D PYTHON_INCLUDE_DIR=/usr/local/include/python3.2 ../blender
 135     On Macs:
 136       cmake -D PYTHON_INCLUDE_DIRS=/System/Library/Frameworks/Python.framework/Versions/3.2/include/python3.2 -G Xcode ../blender
 137
 138     Mote that this should only be needed once per build directory generation because it will keep the overrides in CMakeCache.txt for subsequent runs.
 139
 140
 141
 142     To be continued...
 143
 144     TODO's
 145     ------
 146
 147     1. Get CMake to create proper distribution directories for the various platforms
 148        like scons does.
 149     2. Investigate the viability of using CPack to package installs automatically.
 150     3. Refine this document and write detailed developer's document.
 151     4. Make sure all options (ffmpeg, openexr, quicktime) has proper CMake support
 152        on the various platforms.
 153
 154     /Jacques Beaurain (jbinto)