forked from bartvdbraak/blender
8d9629cef9
* The documentation for BF_QUICKDEBUG et al, missing from previous commit. Also provided by Joseph Eagar.
224 lines
8.2 KiB
Plaintext
224 lines
8.2 KiB
Plaintext
$Id$
|
|
|
|
Blenders SCons build scripts
|
|
============================
|
|
|
|
Introduction
|
|
------------
|
|
|
|
Since the beginning of 2004 Blender has had the SCons system as a
|
|
build option. SCons is a Python-based, accurate build system. The
|
|
scripts that were implemented in the first iteration worked, but
|
|
the system grew quickly into such a state that maintaining it became
|
|
a nightmare, and adding new features was just horrible, leading to
|
|
many hacks without much sense in the overall structure.
|
|
|
|
The rewrite has been waiting for a long time. Jonathan Jacobs provided
|
|
a first overhaul of the scripts, which I used in the first phase of
|
|
the rewrite. To make the system as maintainable as possible I made
|
|
some radical changes, but thanks go to Jonathan for providing me
|
|
with the patch to get started.
|
|
|
|
This document describes the usage of the new SCons scripts. The
|
|
inner workings are described in blender-scons-dev.txt.
|
|
|
|
Building Blender
|
|
----------------
|
|
|
|
To build Blender with the SCons scripts you need a full Python
|
|
install, version 2.3 or later (http://www.python.org) and a SCons
|
|
installation, version v0.96.1.D001 or later (http://www.scons.org).
|
|
|
|
Check from the page
|
|
http://www.blender.org/cms/Getting_Dependencies.135.0.html that you
|
|
have all dependencies needed for building Blender. Note that for
|
|
windows many of these dependencies already come in the lib/windows
|
|
module from CVS.
|
|
|
|
In the base directory of the sources (from now on called $BLENDERHOME)
|
|
you'll see a file named SConstruct. This is the entry point for the
|
|
SCons build system. In a terminal, change to this directory. To just
|
|
build, issue the command 'scons':
|
|
|
|
% scons
|
|
|
|
This will start the build process with default values. Depending
|
|
on your platform you may see colour in your output (non-Windows
|
|
machines). In the the beginning an overview of targets and arguments
|
|
from the command-line is given, then all libraries and binaries to
|
|
build are configured.
|
|
|
|
The build uses BF_BUILDDIR to build into and BF_INSTALLDIR to
|
|
finally copy all needed files to get a proper setup. These
|
|
variabbles have default values for every platform in
|
|
$BLENDERHOME/config/(platform)-config.py. After the build successfully
|
|
completes, you can find everything you need in BF_INSTALLDIR.
|
|
|
|
|
|
Configuring the build
|
|
---------------------
|
|
|
|
The default values for your platform can be found in the directory
|
|
$BLENDERHOME/config. Your platform specific defaults are in
|
|
(platform)-config.py, where platform is one of:
|
|
|
|
- linux2, for machines running Linux
|
|
- win32-vc, for Windows machines, compiling with a Microsoft compiler
|
|
- win32-mingw, for Windows machines, compiling with the MingW compiler
|
|
- darwin, for OS X machines
|
|
(TBD: add cygwin, solaris and freebsd support)
|
|
|
|
These files you will normally not change. If you need to override
|
|
a default value, make a copy of the proper configuration to
|
|
$BLENDERHOME/user-config.py. This file you can modify to your
|
|
likings. Any value set here will override the ones from the
|
|
(platform)-config.py.
|
|
|
|
If you want to quickly test a new setting, you can give the option
|
|
also on the command-line:
|
|
|
|
% scons BF_BUILDDIR=../mybuilddir WITH_BF_OPENEXR=0
|
|
|
|
This command sets the build directory to BF_BUILDDIR and disables
|
|
OpenEXR support.
|
|
|
|
If you need to know what can be set through the command-line, run
|
|
scons with -h:
|
|
|
|
% scons -h
|
|
|
|
This command will print a long list with settable options and what
|
|
every option means. Many of the default values will be empty, and
|
|
from a fresh checkout without a user-config.py the actual values
|
|
are the defaults as per $BLENDERHOME/config/(platform)-config.py
|
|
(unless you have overridden any of them in your
|
|
$BLENDERHOME/user-config.py).
|
|
|
|
NOTE: The best way to avoid confusion is the
|
|
copy $BLENDERHOME/config/(platform)-config.py to
|
|
$BLENDERHOME/user-config.py. You should NEVER have to modify
|
|
$BLENDERHOME/config/(platform)-config.py
|
|
|
|
Configuring the output
|
|
----------------------
|
|
|
|
This rewrite features a cleaner output during the build process. If
|
|
you need to see the full command-line for compiles, then you can
|
|
change that behaviour. Also the use of colours can be changed:
|
|
|
|
% scons BF_FANCY=0
|
|
|
|
This will disable the use of colours.
|
|
|
|
% scons BF_QUIET=0
|
|
|
|
This will give the old, noisy output. Every command-line per
|
|
compile is printed out in its full glory. This is very useful when
|
|
debugging problems with compiling, because you can see what the
|
|
included paths are, what defines are given on the command-line,
|
|
what compiler switches are used, etc.
|
|
|
|
Compiling Only Some Libraries
|
|
-----------------------------
|
|
|
|
Scons now has support for specifying a list of libraries that are
|
|
exclusively compiled, ignoring all other libraries. This is invoked
|
|
with the BF_QUICK arguments; for example:
|
|
|
|
% scons BF_QUICK=src,bf_blenkernel
|
|
|
|
Note that this not the same as passing a list of folders as in the
|
|
makefile's "quicky" command. In Scons, all of Blender's code modules
|
|
are in their own static library; this corresponds to one-lib-per-folder
|
|
in some cases (especially in blender/source/blender).
|
|
|
|
To obtain a list of the libraries, simple fire up scons and CTRL-C out once
|
|
it finishes configuring (and printing to the console) the library list.
|
|
|
|
Compiling Libraries With Debug Profiling
|
|
----------------------------------------
|
|
|
|
Scons has support for specifying a list of libraries that are compiled
|
|
with debug profiling enabled. This is implemented in two commands:
|
|
BF_QUICKDEBUG which is a command-line argument and BF_DEBUG_LIBS, which goes
|
|
in your user-config.py
|
|
|
|
BF_QUICKDEBUG is similar to BF_QUICK:
|
|
|
|
% scons BF_QUICKDEBUG=src,bf_blenkernel,some-other-lib
|
|
|
|
To use BF_DEBUG_LIBS, put something like the following in you user-config.py:
|
|
|
|
BF_DEBUG_LIBS = ['bf_blenlib', 'src', 'some_lib']
|
|
|
|
For instructions on how to find the names of the libraries (folders) you
|
|
wish to use, see the above section. Note that the command BF_DEBUG
|
|
(see below) will override these settings and compile ALL of Blender with
|
|
debug symbols. Also note that BF_QUICKDEBUG and BF_DEBUG_LIBS are combined;
|
|
for example, setting BF_QUICKDEBUG won't overwrite the contents of BF_DEBUG_LIBS.
|
|
|
|
|
|
Supported toolset
|
|
-----------------
|
|
|
|
WINDOWS
|
|
|
|
* msvc, this is a full install of Microsoft Visual C++. You'll
|
|
likely have the .NET Framework SDK, Platform SDK and DX9 SDK
|
|
installed * mstoolkit, this is the free MS VC++ 2003 Toolkit. You
|
|
need to verify you have also the SDKs installed as mentioned
|
|
for msvc. * mingw, this is a minimal MingW install. TBD: write
|
|
proper instructions on getting needed packages.
|
|
|
|
On Windows with all of the three toolset installed you need to
|
|
specify what toolset to use
|
|
|
|
% scons BF_TOOLSET=msvc
|
|
% scons BF_TOOLSET=mstoolkit
|
|
% scons BF_TOOLSET=mingw
|
|
|
|
If you have only the toolkit installed, you will also need to give
|
|
BF_TOOLSET=mstoolkit on the command-line, to make sure everything is
|
|
setup properly. Currently there is no good mechanism to automatically
|
|
determine wether the found 'cl.exe' is from the toolkit or from a
|
|
complete install.
|
|
|
|
LINUX and OS X
|
|
|
|
Currently only the default toolsets are supported for these platforms,
|
|
so nothing special needs to be told to SCons when building. The
|
|
defaults should work fine in most cases.
|
|
|
|
Examples
|
|
--------
|
|
|
|
Build Blender with the defaults:
|
|
|
|
% scons
|
|
|
|
Build Blender, but disable OpenEXR support:
|
|
|
|
% scons WITH_BF_OPENEXR=0
|
|
|
|
Build Blender, enable debug symbols:
|
|
|
|
% scons BF_DEBUG=1
|
|
|
|
Build Blender, install to different directory:
|
|
|
|
% scons BF_INSTALLDIR=/tmp/testbuild
|
|
|
|
Build Blender in /tmp/obj and install to /usr/local:
|
|
|
|
% scons BF_BUILDDIR=/tmp/obj BF_INSTALLDIR=/usr/local
|
|
|
|
Clean BF_BUILDDIR:
|
|
|
|
% scons clean
|
|
|
|
Clean out the installed files:
|
|
|
|
% scons -c
|
|
|
|
/Nathan Letwory (jesterKing)
|