merge from 23153 to 23595
[blender.git] / doc / blender-cmake.txt
1 $Id$
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