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