doc/blender-cmake.txt

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