doc/blender-scons.txt

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