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 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     Compiling Only Some Libraries
 122     -----------------------------
 123
 124     Scons now has support for specifying a list of libraries that are
 125     exclusively compiled, ignoring all other libraries.  This is invoked
 126     with the BF_QUICK arguments; for example:
 127
 128         % scons BF_QUICK=src,bf_blenkernel
 129
 130     Note that this not the same as passing a list of folders as in the
 131     makefile's "quicky" command.  In Scons, all of Blender's code modules
 132     are in their own static library; this corresponds to one-lib-per-folder
 133     in some cases (especially in blender/source/blender).
 134
 135     To obtain a list of the libraries, simple fire up scons and CTRL-C out once
 136     it finishes configuring (and printing to the console) the library list.
 137
 138     Compiling Libraries With Debug Profiling
 139     ----------------------------------------
 140
 141     Scons has support for specifying a list of libraries that are compiled
 142     with debug profiling enabled.  This is implemented in two commands:
 143     BF_QUICKDEBUG which is a command-line argument and BF_DEBUG_LIBS, which goes
 144     in your user-config.py
 145
 146     BF_QUICKDEBUG is similar to BF_QUICK:
 147
 148         % scons BF_QUICKDEBUG=src,bf_blenkernel,some-other-lib
 149
 150     To use BF_DEBUG_LIBS, put something like the following in you user-config.py:
 151
 152         BF_DEBUG_LIBS = ['bf_blenlib', 'src', 'some_lib']
 153
 154     For instructions on how to find the names of the libraries (folders) you
 155     wish to use, see the above section.  Note that the command BF_DEBUG
 156     (see below) will override these settings and compile ALL of Blender with
 157     debug symbols.  Also note that BF_QUICKDEBUG and BF_DEBUG_LIBS are combined;
 158     for example, setting BF_QUICKDEBUG won't overwrite the contents of BF_DEBUG_LIBS.
 159
 160
 161     Supported toolset
 162     -----------------
 163
 164     WINDOWS
 165
 166         * msvc, this is a full install of Microsoft Visual C++. You'll
 167         likely have the .NET Framework SDK, Platform SDK and DX9 SDK
 168         installed * mstoolkit, this is the free MS VC++ 2003 Toolkit. You
 169         need to verify you have also the SDKs installed as mentioned
 170         for msvc.  * mingw, this is a minimal MingW install. TBD: write
 171         proper instructions on getting needed packages.
 172
 173     On Windows with all of the three toolset installed you need to
 174     specify what toolset to use
 175
 176         % scons BF_TOOLSET=msvc
 177         % scons BF_TOOLSET=mstoolkit
 178         % scons BF_TOOLSET=mingw
 179
 180     If you have only the toolkit installed, you will also need to give
 181     BF_TOOLSET=mstoolkit on the command-line, to make sure everything is
 182     setup properly. Currently there is no good mechanism to automatically
 183     determine wether the found 'cl.exe' is from the toolkit or from a
 184     complete install.
 185
 186     LINUX and OS X
 187
 188     Currently only the default toolsets are supported for these platforms,
 189     so nothing special needs to be told to SCons when building. The
 190     defaults should work fine in most cases.
 191
 192     Examples
 193     --------
 194
 195     Build Blender with the defaults:
 196
 197         % scons
 198
 199     Build Blender, but disable OpenEXR support:
 200
 201         % scons WITH_BF_OPENEXR=0
 202
 203     Build Blender, enable debug symbols:
 204
 205         % scons BF_DEBUG=1
 206
 207     Build Blender, install to different directory:
 208
 209         % scons BF_INSTALLDIR=/tmp/testbuild
 210
 211     Build Blender in /tmp/obj and install to /usr/local:
 212
 213         % scons BF_BUILDDIR=/tmp/obj BF_INSTALLDIR=/usr/local
 214
 215     Clean BF_BUILDDIR:
 216
 217         % scons clean
 218
 219     Clean out the installed files:
 220
 221         % scons -c
 222
 223     /Nathan Letwory (jesterKing)