doc/build_systems/scons.txt

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