doc/blender-scons.txt

   1 $Id: blender-scons.txt 10539 2007-04-17 05:21:37Z jesterking $
   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     Not installing
 164     --------------
 165
 166     If you dont want to install the build result, you can use the following option either
 167     on the commandline or in your user-config.py :
 168
 169         WITHOUT_BF_INSTALL='true'
 170
 171     by default, this is set to 'false', and so the build is installed
 172
 173
 174     Supported toolset
 175     -----------------
 176
 177     WINDOWS
 178
 179         * msvc, this is a full install of Microsoft Visual C++. You'll
 180         likely have the .NET Framework SDK, Platform SDK and DX9 SDK
 181         installed * mstoolkit, this is the free MS VC++ 2003 Toolkit. You
 182         need to verify you have also the SDKs installed as mentioned
 183         for msvc.  * mingw, this is a minimal MingW install. TBD: write
 184         proper instructions on getting needed packages.
 185
 186     On Windows with all of the three toolset installed you need to
 187     specify what toolset to use
 188
 189         % scons BF_TOOLSET=msvc
 190         % scons BF_TOOLSET=mstoolkit
 191         % scons BF_TOOLSET=mingw
 192
 193     If you have only the toolkit installed, you will also need to give
 194     BF_TOOLSET=mstoolkit on the command-line, to make sure everything is
 195     setup properly. Currently there is no good mechanism to automatically
 196     determine wether the found 'cl.exe' is from the toolkit or from a
 197     complete install.
 198
 199     LINUX and OS X
 200
 201     Currently only the default toolsets are supported for these platforms,
 202     so nothing special needs to be told to SCons when building. The
 203     defaults should work fine in most cases.
 204
 205     Examples
 206     --------
 207
 208     Build Blender with the defaults:
 209
 210         % scons
 211
 212     Build Blender, but disable OpenEXR support:
 213
 214         % scons WITH_BF_OPENEXR=0
 215
 216     Build Blender, enable debug symbols:
 217
 218         % scons BF_DEBUG=1
 219
 220     Build Blender, install to different directory:
 221
 222         % scons BF_INSTALLDIR=/tmp/testbuild
 223
 224     Build Blender in /tmp/obj and install to /usr/local:
 225
 226         % scons BF_BUILDDIR=/tmp/obj BF_INSTALLDIR=/usr/local
 227
 228     Clean BF_BUILDDIR:
 229
 230         % scons clean
 231
 232     Clean out the installed files:
 233
 234         % scons -c
 235
 236     /Nathan Letwory (jesterKing)