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