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). We already provide
  30     a scons-local installation, which can be found in the scons/ subdirectory.
  31     This document uses the scons-local installation for its examples.
  32
  33     Check from the page
  34     http://www.blender.org/development/building-blender/getting-dependencies/
  35     that you have all dependencies needed for building Blender. Note that for
  36     windows many of these dependencies already come in the lib/windows module
  37     from CVS.
  38
  39     In the base directory of the sources (from now on called $BLENDERHOME)
  40     you'll see a file named SConstruct. This is the entry point for the
  41     SCons build system. In a terminal, change to this directory. To just
  42     build, start the SCons entry script on Windows (will be used for the remainder
  43     of this document):
  44
  45         % python scons\scons.py
  46
  47     On a Unix-compatible system it would be
  48
  49         % python ./scons/scons.py
  50
  51     This will start the build process with default values. Depending
  52     on your platform you may see colour in your output (non-Windows
  53     machines). In the the beginning an overview of targets and arguments
  54     from the command-line is given, then all libraries and binaries to
  55     build are configured.
  56
  57     The build uses BF_BUILDDIR to build into and BF_INSTALLDIR to
  58     finally copy all needed files to get a proper setup. The BF_DOCDIR is
  59     used to generate Blender Python documentation files to. These
  60     variables have default values for every platform in
  61     $BLENDERHOME/config/(platform)-config.py. After the build successfully
  62     completes, you can find everything you need in BF_INSTALLDIR.
  63
  64     If you want to create the installer package of Blender on Windows you'll
  65     need to install nullsoft scriptable install system from http://nsis.sf.net.
  66     As an extra dependency, you need the MoreInfo plugin too. The creation of
  67     the installer is tied into the build process and can be triggered with:
  68
  69         % python scons\scons.py nsis
  70
  71
  72     Configuring the build
  73     ---------------------
  74
  75     The default values for your platform can be found in the directory
  76     $BLENDERHOME/config. Your platform specific defaults are in
  77     (platform)-config.py, where platform is one of:
  78
  79         - linux2, for machines running Linux
  80         - win32-vc, for Windows machines, compiling with a Microsoft compiler
  81         - win32-mingw, for Windows machines, compiling with the MingW compiler
  82         - darwin, for OS X machines
  83         (TBD: add cygwin, solaris and freebsd support)
  84
  85     These files you will normally not change. If you need to override
  86     a default value, make a file called  $BLENDERHOME/user-config.py, and copy
  87     settings from the config/(platform)-config.py that you want to change. Don't
  88     copy the entire file (unless explicitely stated in the configuration file),
  89     because you may not get updated options you don't change yourself, which may
  90     result in build errors.
  91
  92     You can use BF_CONFIG argument to override the default user-config.py
  93     check. This is just like the user-config.py, but just with another name:
  94
  95         % python scons\scons.py BF_CONFIG=myownsettings
  96
  97     If you want to quickly test a new setting, you can give the option
  98     also on the command-line:
  99
 100         % python scons\scons.py BF_BUILDDIR=../mybuilddir WITH_BF_OPENEXR=0
 101
 102     This command sets the build directory to BF_BUILDDIR and disables
 103     OpenEXR support.
 104
 105     If you need to know what can be set through the command-line, run
 106     scons with -h:
 107
 108         % python scons\scons.py -h
 109
 110     This command will print a long list with settable options and what
 111     every option means. Many of the default values will be empty, and
 112     from a fresh checkout without a user-config.py the actual values
 113     are the defaults as per $BLENDERHOME/config/(platform)-config.py
 114     (unless you have overridden any of them in your
 115     $BLENDERHOME/user-config.py).
 116
 117     NOTE: The best way to avoid confusion is the
 118     copy $BLENDERHOME/config/(platform)-config.py to
 119     $BLENDERHOME/user-config.py. You should NEVER have to modify
 120     $BLENDERHOME/config/(platform)-config.py
 121
 122     Configuring the output
 123     ----------------------
 124
 125     This rewrite features a cleaner output during the build process. If
 126     you need to see the full command-line for compiles, then you can
 127     change that behaviour. Also the use of colours can be changed:
 128
 129         % python scons\scons.py BF_FANCY=0
 130
 131     This will disable the use of colours.
 132
 133         % python scons\scons.py BF_QUIET=0
 134
 135     This will give the old, noisy output. Every command-line per
 136     compile is printed out in its full glory. This is very useful when
 137     debugging problems with compiling, because you can see what the
 138     included paths are, what defines are given on the command-line,
 139     what compiler switches are used, etc.
 140
 141     Compiling Only Some Libraries
 142     -----------------------------
 143
 144     Our implementation now has support for specifying a list of libraries that are
 145     exclusively compiled, ignoring all other libraries.  This is invoked
 146     with the BF_QUICK arguments; for example:
 147
 148         % python scons\scons.py BF_QUICK=src,bf_blenkernel
 149
 150     Note that this not the same as passing a list of folders as in the
 151     makefile's "quicky" command.  In Scons, all of Blender's code modules
 152     are in their own static library; this corresponds to one-lib-per-folder
 153     in some cases (especially in blender/source/blender).
 154
 155     To obtain a list of the libraries, simple fire up scons and CTRL-C out once
 156     it finishes configuring (and printing to the console) the library list.
 157
 158     Compiling Libraries With Debug Profiling
 159     ----------------------------------------
 160
 161     Scons has support for specifying a list of libraries that are compiled
 162     with debug profiling enabled.  This is implemented in two commands:
 163     BF_QUICKDEBUG which is a command-line argument and BF_DEBUG_LIBS, which goes
 164     in your user-config.py
 165
 166     BF_QUICKDEBUG is similar to BF_QUICK:
 167
 168         % python scons\scons.py BF_QUICKDEBUG=src,bf_blenkernel,some-other-lib
 169
 170     To use BF_DEBUG_LIBS, put something like the following in you user-config.py:
 171
 172         BF_DEBUG_LIBS = ['bf_blenlib', 'src', 'some_lib']
 173
 174     For instructions on how to find the names of the libraries (folders) you
 175     wish to use, see the above section.  Note that the command BF_DEBUG
 176     (see below) will override these settings and compile ALL of Blender with
 177     debug symbols.  Also note that BF_QUICKDEBUG and BF_DEBUG_LIBS are combined;
 178     for example, setting BF_QUICKDEBUG won't overwrite the contents of BF_DEBUG_LIBS.
 179
 180     Supported toolset
 181     -----------------
 182
 183     WINDOWS
 184
 185         * msvc, this is a full install of Microsoft Visual C++. You'll
 186         likely have the .NET Framework SDK, Platform SDK and DX9 SDK
 187         installed * mstoolkit, this is the free MS VC++ 2003 Toolkit. You
 188         need to verify you have also the SDKs installed as mentioned
 189         for msvc.  * mingw, this is a minimal MingW install. TBD: write
 190         proper instructions on getting needed packages.
 191
 192     On Windows with all of the three toolset installed you need to
 193     specify what toolset to use
 194
 195         % python scons\scons.py BF_TOOLSET=msvc
 196         % python scons\scons.py BF_TOOLSET=mingw
 197
 198     LINUX and OS X
 199
 200     Currently only the default toolsets are supported for these platforms,
 201     so nothing special needs to be told to SCons when building. The
 202     defaults should work fine in most cases.
 203
 204     Examples
 205     --------
 206
 207     Build Blender with the defaults:
 208
 209         % python scons\scons.py
 210
 211     Build Blender, but disable OpenEXR support:
 212
 213         % python scons\scons.py WITH_BF_OPENEXR=0
 214
 215     Build Blender, enable debug symbols:
 216
 217         % python scons\scons.py BF_DEBUG=1
 218
 219     Build Blender, install to different directory:
 220
 221         % python scons\scons.py BF_INSTALLDIR=../myown/installdir
 222
 223     Build Blender in ../myown/builddir and install to ../myown/installdir:
 224
 225         % python scons\scons.py BF_BUILDDIR=../myown/builddir BF_INSTALLDIR=../myown/installdir
 226
 227     Clean BF_BUILDDIR:
 228
 229         % python scons\scons.py clean
 230
 231     /Nathan Letwory (jesterKing)