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