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