forked from bartvdbraak/blender
231 lines
9.1 KiB
Plaintext
231 lines
9.1 KiB
Plaintext
|
|
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 scons-dev.txt.
|
|
|
|
Building Blender
|
|
----------------
|
|
|
|
To build Blender with the SCons scripts you need a full Python
|
|
install, version 2.4 or later (http://www.python.org). We already provide
|
|
a scons-local installation, which can be found in the scons/ subdirectory.
|
|
This document uses the scons-local installation for its examples.
|
|
|
|
Check from the page
|
|
http://www.blender.org/development/building-blender/getting-dependencies/
|
|
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, start the SCons entry script on Windows (will be used for the remainder
|
|
of this document):
|
|
|
|
% python scons\scons.py
|
|
|
|
On a Unix-compatible system it would be
|
|
|
|
% python ./scons/scons.py
|
|
|
|
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. The BF_DOCDIR is
|
|
used to generate Blender Python documentation files to. These
|
|
variables 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.
|
|
|
|
If you want to create the installer package of Blender on Windows you'll
|
|
need to install nullsoft scriptable install system from http://nsis.sf.net.
|
|
As an extra dependency, you need the MoreInfo plugin too. The creation of
|
|
the installer is tied into the build process and can be triggered with:
|
|
|
|
% python scons\scons.py nsis
|
|
|
|
|
|
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:
|
|
|
|
- linux, 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 file called $BLENDERHOME/user-config.py, and copy
|
|
settings from the config/(platform)-config.py that you want to change. Don't
|
|
copy the entire file (unless explicitely stated in the configuration file),
|
|
because you may not get updated options you don't change yourself, which may
|
|
result in build errors.
|
|
|
|
You can use BF_CONFIG argument to override the default user-config.py
|
|
check. This is just like the user-config.py, but just with another name:
|
|
|
|
% python scons\scons.py BF_CONFIG=myownsettings
|
|
|
|
If you want to quickly test a new setting, you can give the option
|
|
also on the command-line:
|
|
|
|
% python scons\scons.py 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:
|
|
|
|
% python scons\scons.py -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:
|
|
|
|
% python scons\scons.py BF_FANCY=0
|
|
|
|
This will disable the use of colours.
|
|
|
|
% python scons\scons.py 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
|
|
-----------------------------
|
|
|
|
Our implementation 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:
|
|
|
|
% python scons\scons.py 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:
|
|
|
|
% python scons\scons.py 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
|
|
|
|
% python scons\scons.py BF_TOOLSET=msvc
|
|
% python scons\scons.py BF_TOOLSET=mingw
|
|
|
|
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:
|
|
|
|
% python scons\scons.py
|
|
|
|
Build Blender, but disable OpenEXR support:
|
|
|
|
% python scons\scons.py WITH_BF_OPENEXR=0
|
|
|
|
Build Blender, enable debug symbols:
|
|
|
|
% python scons\scons.py BF_DEBUG=1
|
|
|
|
Build Blender, install to different directory:
|
|
|
|
% python scons\scons.py BF_INSTALLDIR=../myown/installdir
|
|
|
|
Build Blender in ../myown/builddir and install to ../myown/installdir:
|
|
|
|
% python scons\scons.py BF_BUILDDIR=../myown/builddir BF_INSTALLDIR=../myown/installdir
|
|
|
|
Clean BF_BUILDDIR:
|
|
|
|
% python scons\scons.py clean
|
|
|
|
/Nathan Letwory (jesterKing)
|