==SCons==
[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.3 or later (http://www.python.org) and a SCons
30     installation, version v0.96.1.D001 or later (http://www.scons.org).
31
32     Check from the page
33     http://www.blender.org/cms/Getting_Dependencies.135.0.html that you
34     have all dependencies needed for building Blender. Note that for
35     windows many of these dependencies already come in the lib/windows
36     module 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
58     Configuring the build
59     ---------------------
60
61     The default values for your platform can be found in the directory
62     $BLENDERHOME/config. Your platform specific defaults are in
63     (platform)-config.py, where platform is one of:
64
65         - linux2, for machines running Linux
66         - win32-vc, for Windows machines, compiling with a Microsoft compiler
67         - win32-mingw, for Windows machines, compiling with the MingW compiler
68         - darwin, for OS X machines
69         (TBD: add cygwin, solaris and freebsd support)
70
71     These files you will normally not change. If you need to override
72     a default value, make a copy of the proper configuration to
73     $BLENDERHOME/user-config.py. This file you can modify to your
74     likings. Any value set here will override the ones from the
75     (platform)-config.py.
76
77     If you want to quickly test a new setting, you can give the option
78     also on the command-line:
79
80         % scons BF_BUILDDIR=../mybuilddir WITH_BF_OPENEXR=0
81
82     This command sets the build directory to BF_BUILDDIR and disables
83     OpenEXR support.
84
85     If you need to know what can be set through the command-line, run
86     scons with -h:
87
88         % scons -h
89
90     This command will print a long list with settable options and what
91     every option means. Many of the default values will be empty, and
92     from a fresh checkout without a user-config.py the actual values
93     are the defaults as per $BLENDERHOME/config/(platform)-config.py
94     (unless you have overridden any of them in your
95     $BLENDERHOME/user-config.py).
96
97     NOTE: The best way to avoid confusion is the
98     copy $BLENDERHOME/config/(platform)-config.py to
99     $BLENDERHOME/user-config.py. You should NEVER have to modify
100     $BLENDERHOME/config/(platform)-config.py
101
102     Configuring the output
103     ----------------------
104
105     This rewrite features a cleaner output during the build process. If
106     you need to see the full command-line for compiles, then you can
107     change that behaviour. Also the use of colours can be changed:
108
109         % scons BF_FANCY=0
110
111     This will disable the use of colours.
112
113         % scons BF_QUIET=0
114
115     This will give the old, noisy output. Every command-line per
116     compile is printed out in its full glory. This is very useful when
117     debugging problems with compiling, because you can see what the
118     included paths are, what defines are given on the command-line,
119     what compiler switches are used, etc.
120
121
122     Supported toolset
123     -----------------
124
125     WINDOWS
126
127         * msvc, this is a full install of Microsoft Visual C++. You'll
128         likely have the .NET Framework SDK, Platform SDK and DX9 SDK
129         installed * mstoolkit, this is the free MS VC++ 2003 Toolkit. You
130         need to verify you have also the SDKs installed as mentioned
131         for msvc.  * mingw, this is a minimal MingW install. TBD: write
132         proper instructions on getting needed packages.
133
134     On Windows with all of the three toolset installed you need to
135     specify what toolset to use
136
137         % scons BF_TOOLSET=msvc
138         % scons BF_TOOLSET=mstoolkit
139         % scons BF_TOOLSET=mingw
140
141     If you have only the toolkit installed, you will also need to give
142     BF_TOOLSET=mstoolkit on the command-line, to make sure everything is
143     setup properly. Currently there is no good mechanism to automatically
144     determine wether the found 'cl.exe' is from the toolkit or from a
145     complete install.
146
147     LINUX and OS X
148
149     Currently only the default toolsets are supported for these platforms,
150     so nothing special needs to be told to SCons when building. The
151     defaults should work fine in most cases.
152
153     Examples
154     --------
155
156     Build Blender with the defaults:
157
158         % scons
159
160     Build Blender, but disable OpenEXR support:
161
162         % scons WITH_BF_OPENEXR=0
163
164     Build Blender, enable debug symbols:
165
166         % scons BF_DEBUG=1
167
168     Build Blender, install to different directory:
169
170         % scons BF_INSTALLDIR=/tmp/testbuild
171
172     Build Blender in /tmp/obj and install to /usr/local:
173
174         % scons BF_BUILDDIR=/tmp/obj BF_INSTALLDIR=/usr/local
175
176     Clean BF_BUILDDIR:
177
178         % scons clean
179
180     Clean out the installed files:
181
182         % scons -c
183
184     /Nathan Letwory (jesterKing)