BGE: New isDynamicSuspended python attribute
[blender.git] / doc / build_systems / scons.txt
1
2     Blenders SCons build scripts
3     ============================
4
5     Introduction
6     ------------
7
8     Since the beginning of 2004 Blender has had the SCons system as a
9     build option. SCons is a Python-based, accurate build system. The
10     scripts that were implemented in the first iteration worked, but
11     the system grew quickly into such a state that maintaining it became
12     a nightmare, and adding new features was just horrible, leading to
13     many hacks without much sense in the overall structure.
14
15     The rewrite has been waiting for a long time. Jonathan Jacobs provided
16     a first overhaul of the scripts, which I used in the first phase of
17     the rewrite. To make the system as maintainable as possible I made
18     some radical changes, but thanks go to Jonathan for providing me
19     with the patch to get started.
20
21     This document describes the usage of the new SCons scripts. The
22     inner workings are described in scons-dev.txt.
23
24     Building Blender
25     ----------------
26
27     To build Blender with the SCons scripts you need a full Python
28     install, version 2.4 or later (http://www.python.org). We already provide
29     a scons-local installation, which can be found in the scons/ subdirectory.
30     This document uses the scons-local installation for its examples.
31
32     For build instructions, including dependencies, consult the appropriate
33     section for your platform at
34     http://wiki.blender.org/index.php/Dev:Doc/Building_Blender. Note that for
35     windows many of these dependencies already come in the lib/windows module
36     from CVS.
37
38     In the base directory of the sources (from now on called $BLENDERHOME)
39     you'll see a file named SConstruct. This is the entry point for the
40     SCons build system. In a terminal, change to this directory. To just
41     build, start the SCons entry script on Windows (will be used for the remainder
42     of this document):
43
44         % python scons\scons.py
45
46     On a Unix-compatible system it would be
47
48         % python ./scons/scons.py
49
50     This will start the build process with default values. Depending
51     on your platform you may see color in your output (non-Windows
52     machines). In the the beginning an overview of targets and arguments
53     from the command-line is given, then all libraries and binaries to
54     build are configured.
55
56     The build uses BF_BUILDDIR to build into and BF_INSTALLDIR to finally copy
57     all needed files to get a proper setup. The BF_DOCDIR is used to generate
58     Blender Python documentation files to. These variables have default values
59     for every platform in
60     $BLENDERHOME/build_files/scons/config/(platform)-config.py. See the next
61     section of this document for how to customize these paths. After the build
62     successfully completes, you can find everything you need in BF_INSTALLDIR.
63
64     If you want to create the installer package of Blender on Windows you'll
65     need to install nullsoft scriptable install system from http://nsis.sf.net.
66     As an extra dependency, you need the MoreInfo plugin too. The creation of
67     the installer is tied into the build process and can be triggered with:
68
69         % python scons\scons.py nsis
70
71
72     Configuring the build
73     ---------------------
74
75     The default values for your platform can be found in the directory
76     $BLENDERHOME/build_files/scons/config. Your platform specific defaults are
77     in (platform)-config.py, where platform is one of:
78
79         - linux, for machines running Linux
80         - win32-vc, for Windows machines, compiling with a Microsoft compiler
81         - win32-mingw, for Windows machines, compiling with the MingW compiler
82         - darwin, for OS X machines
83         (TBD: add cygwin, solaris and freebsd support)
84
85     These files you will normally not change. If you need to override a
86     default value, make a file called $BLENDERHOME/user-config.py, and copy
87     settings from the build_files/scons/config/(platform)-config.py that you
88     want to change. Don't copy the entire file (unless explicitly stated in
89     the configuration file), because you may not get updated options you don't
90     change yourself, which may result in build errors. You should NEVER have
91     to modify $BLENDERHOME/build_files/scons/config/(platform)-config.py.
92
93     You can use BF_CONFIG argument to override the default user-config.py
94     check. This is just like the user-config.py, but just with another name:
95
96         % python scons\scons.py BF_CONFIG=myownsettings
97
98     If you want to quickly test a new setting, you can give the option
99     also on the command-line:
100
101         % python scons\scons.py BF_BUILDDIR=../mybuilddir WITH_BF_OPENEXR=0
102
103     This command sets the build directory to BF_BUILDDIR and disables
104     OpenEXR support.
105
106     If you need to know what can be set through the command-line, run
107     scons with -h:
108
109         % python scons\scons.py -h
110
111     This command will print a long list with settable options and what
112     every option means. Many of the default values will be empty, and
113     from a fresh checkout without a user-config.py the actual values
114     are the defaults as per $BLENDERHOME/config/(platform)-config.py
115     (unless you have overridden any of them in your
116     $BLENDERHOME/user-config.py).
117
118     Configuring the output
119     ----------------------
120
121     This rewrite features a cleaner output during the build process. If
122     you need to see the full command-line for compiles, then you can
123     change that behaviour. Also the use of colors can be changed:
124
125         % python scons\scons.py BF_FANCY=0
126
127     This will disable the use of colors.
128
129         % python scons\scons.py BF_QUIET=0
130
131     This will give the old, noisy output. Every command-line per
132     compile is printed out in its full glory. This is very useful when
133     debugging problems with compiling, because you can see what the
134     included paths are, what defines are given on the command-line,
135     what compiler switches are used, etc.
136
137     Compiling Only Some Libraries
138     -----------------------------
139     
140     Our implementation now has support for specifying a list of libraries that are
141     exclusively compiled, ignoring all other libraries.  This is invoked 
142     with the BF_QUICK arguments; for example:
143     
144         % python scons\scons.py BF_QUICK=src,bf_blenkernel
145     
146     Note that this not the same as passing a list of folders as in the 
147     makefile's "quicky" command.  In Scons, all of Blender's code modules
148     are in their own static library; this corresponds to one-lib-per-folder 
149     in some cases (especially in blender/source/blender).
150     
151     To obtain a list of the libraries, simple fire up scons and CTRL-C out once 
152     it finishes configuring (and printing to the console) the library list.
153     
154     Compiling Libraries With Debug Profiling
155     ----------------------------------------
156     
157     Scons has support for specifying a list of libraries that are compiled
158     with debug profiling enabled.  This is implemented in two commands:
159     BF_QUICKDEBUG which is a command-line argument and BF_DEBUG_LIBS, which goes
160     in your user-config.py
161     
162     BF_QUICKDEBUG is similar to BF_QUICK:
163     
164         % python scons\scons.py BF_QUICKDEBUG=src,bf_blenkernel,some-other-lib
165     
166     To use BF_DEBUG_LIBS, put something like the following in you user-config.py:
167     
168         BF_DEBUG_LIBS = ['bf_blenlib', 'src', 'some_lib']
169         
170     For instructions on how to find the names of the libraries (folders) you 
171     wish to use, see the above section.  Note that the command BF_DEBUG 
172     (see below) will override these settings and compile ALL of Blender with
173     debug symbols.  Also note that BF_QUICKDEBUG and BF_DEBUG_LIBS are combined;
174     for example, setting BF_QUICKDEBUG won't overwrite the contents of BF_DEBUG_LIBS.
175
176     Supported toolset
177     -----------------
178
179     WINDOWS
180
181         * msvc, this is a full install of Microsoft Visual C++. You'll
182         likely have the .NET Framework SDK, Platform SDK and DX9 SDK
183         installed * mstoolkit, this is the free MS VC++ 2003 Toolkit. You
184         need to verify you have also the SDKs installed as mentioned
185         for msvc.  * mingw, this is a minimal MingW install. TBD: write
186         proper instructions on getting needed packages.
187
188     On Windows with all of the three toolset installed you need to
189     specify what toolset to use
190
191         % python scons\scons.py BF_TOOLSET=msvc
192         % python scons\scons.py BF_TOOLSET=mingw
193
194     LINUX and OS X
195
196     Currently only the default toolsets are supported for these platforms,
197     so nothing special needs to be told to SCons when building. The
198     defaults should work fine in most cases.
199
200     Examples
201     --------
202
203     Build Blender with the defaults:
204
205         % python scons\scons.py
206
207     Build Blender, but disable OpenEXR support:
208
209         % python scons\scons.py WITH_BF_OPENEXR=0
210
211     Build Blender, enable debug symbols:
212
213         % python scons\scons.py BF_DEBUG=1
214
215     Build Blender, install to different directory:
216
217         % python scons\scons.py BF_INSTALLDIR=../myown/installdir
218
219     Build Blender in ../myown/builddir and install to ../myown/installdir:
220
221         % python scons\scons.py BF_BUILDDIR=../myown/builddir BF_INSTALLDIR=../myown/installdir
222
223     Clean BF_BUILDDIR:
224
225         % python scons\scons.py clean
226
227     /Nathan Letwory (jesterKing)