svn merge ^/trunk/blender -r48004:48011
[blender.git] / 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)