forked from bartvdbraak/blender
== SCons ==
* Added a user and a developer doc for the upcoming SCons commits. These documents should get most people started after the commit of the new scripts is a fact.
This commit is contained in:
Nathan Letwory
parent
faff1cf46b
commit
e46b74d18e
194
doc/blender-scons-dev.txt
Normal file
194
doc/blender-scons-dev.txt
Normal file
@ -0,0 +1,194 @@
|
||||
$Id$
|
||||
|
||||
|
||||
Internals of Blenders SCons scripts
|
||||
===================================
|
||||
|
||||
Scope
|
||||
------
|
||||
This document describes the architecture of the SCons scripts for
|
||||
Blender. An overview of available functionality and how to modify,
|
||||
extend and maintain the system.
|
||||
|
||||
Audience
|
||||
--------
|
||||
This document is for developers who need to modify the system,
|
||||
ie. add or remove new libraries, add new arguments for SCons, etc.
|
||||
|
||||
Files and their meaning
|
||||
-----------------------
|
||||
|
||||
The main entry point for the build system is the SConstruct-file in
|
||||
$BLENDERHOME. This file creates the first BlenderEnvironment to work
|
||||
with, reads in options, and sets up some directory structures. Further
|
||||
it defines some targets.
|
||||
|
||||
Platform-specific configurations are in $BLENDERHOME/config. The
|
||||
filenames have the form (platform)-config.py, where platform one of:
|
||||
|
||||
* darwin
|
||||
* linux2
|
||||
* win32-mingw
|
||||
* win32-vc
|
||||
|
||||
The user can override options by creating a file
|
||||
$BLENDERHOME/user-config.py. It can have any option from
|
||||
(platform)-config.py. Options in this file will override the platform
|
||||
defaults.
|
||||
|
||||
Much of the actual functionality can be found in the python scripts
|
||||
in the directory $BLENDERHOME/tools, with Blender.py defining the
|
||||
bulk of the functionality. btools.py has some helper functions, and
|
||||
bcolors.py is for the terminal colours. mstoolkit.py and crossmingw.py
|
||||
are modules which set up SCons for the MS VC++ 2003 toolkit and
|
||||
the cross-compile toolset for compiling Windows binaries on Linux
|
||||
respectively. Note: the cross-compile doesn't work yet for Blender,
|
||||
but is added in preparation for having it work in the distant future.
|
||||
|
||||
BlenderEnvironment
|
||||
------------------
|
||||
|
||||
The module Blender.py implements a BlenderEnvironment class, derived
|
||||
from the SConsEnvironment of SCons. This is done to wrap some often
|
||||
used functionality. The BlenderEnvironment offers two important
|
||||
wrappers: BlenderProg() and BlenderLib(). The first one is used to
|
||||
specify a binary to be built, the second one is used to specify what
|
||||
static library is built from given sources.
|
||||
|
||||
Build a static library called "somelib". The system handles library
|
||||
pre- and suffixes automatically, you don't need to bother yourself
|
||||
with these details:
|
||||
|
||||
env = BlenderEnvironment(ENV = os.environ) # create an environment
|
||||
env.BlenderLib(libname="somelib", sources=['list.c','with.c','sources.c'],
|
||||
includes=['/list/with/include/paths', '.', '..'],
|
||||
defines=['LIST_WITH', 'CPP_DEFINES', 'TO_USE'],
|
||||
libtype=['blender', 'common'] # this is a list with libtypes. Normally you don't
|
||||
# need to specify this, but if you encounter linking
|
||||
# problems you may need this
|
||||
priority=[10, 20] # Priorities, list as long as libtype, priority per type
|
||||
compileflags=['/O2'] # List of compile flags needed for this particular library.
|
||||
# used only in rare cases, like SOLID, qhull and Bullet
|
||||
)
|
||||
|
||||
There should be no need to ever add an extra BlenderProg to the
|
||||
existing ones in SConstruct, see that file for its use, and Blender.py
|
||||
for its implementation.
|
||||
|
||||
The new system works so that using these wrappers, has all libraries
|
||||
(and programs) register with a central repository. This means that
|
||||
adding a new library is as easy as just creating the new SConscript
|
||||
and making sure that it gets called properly. Linking and such will
|
||||
then be handled automatically.
|
||||
|
||||
If you want that adding new source files for a certain library
|
||||
is handled automatically, you can use the Glob() function from
|
||||
the BlenderEnvironment to create lists of needed files. See
|
||||
$BLENDERHOME/source/blender/src/SConscript for an example. Keep in
|
||||
mind that this will add any new file that complies to the rule given
|
||||
to the Glob() function. There are a few (external) libraries with
|
||||
which this can't be used, because it'd take files that shouldn't be
|
||||
compiled, and create subsequentially problems during the linking stage
|
||||
(like SOLID, qhull, Bullet).
|
||||
|
||||
Linking order and priorities
|
||||
----------------------------
|
||||
|
||||
As shown above, you can give a library a priority in a certain
|
||||
group. If you need to make sure that a Blender library is linked
|
||||
before or after another one, you can give it a priority. To debug
|
||||
the priorities us BF_PRIORITYLIST=1 on the command-line while running
|
||||
a build.
|
||||
|
||||
% scons BF_PRIORITY_LIST=1
|
||||
|
||||
This will give a list with values suggested by the system. Make
|
||||
changes to all SConscripts in question to reflect or change the
|
||||
values given by this command. ALWAYS check this after adding a new
|
||||
internal, external library or core library, and make sure there are
|
||||
sane values. You can use large and negative numbers to test with,
|
||||
but after you've got a working linking order, do change the system
|
||||
to reflect BF_PRIORITY_LIST values.
|
||||
|
||||
Also, if you find that a library needs to be given multiple times to
|
||||
the linker, you can do that by giving a python list with the names
|
||||
of the available library types. They are currently:
|
||||
|
||||
B.possible_types = ['core', 'common', 'blender', 'intern',
|
||||
'international', 'game', 'game2',
|
||||
'player', 'player2', 'system']
|
||||
|
||||
More groups can be added, but that should be carefully considered,
|
||||
as it may lead to large-scale changes. The current amount of libraries
|
||||
should suffice.
|
||||
|
||||
The central repository is utilised in the SConstruct in two
|
||||
ways. Firstly, it is used to determine the order of all static
|
||||
libraries to link into the main Blender executable. Secondly, it
|
||||
is used to keep track of all built binaries and their location,
|
||||
so that they can be properly copied to BF_INSTALLDIR.
|
||||
|
||||
The libraries can be fetched in their priority order with
|
||||
create_blender_liblist from Blender.py, see the SConstruct on how
|
||||
it is used.
|
||||
|
||||
The program repository is the global list program_list from
|
||||
Blender.py. See SConstruct for its usage.
|
||||
|
||||
|
||||
Adding a new option and libraries
|
||||
---------------------------------
|
||||
|
||||
Lets say we want to add WITH_BF_NEWLIB, which will
|
||||
enable or disable a new feature library with sources in
|
||||
$BLENDERHOME/source/blender/newlib. This 'newlib' needs external
|
||||
headers from a 3rd party library '3rdparty'. For this we want to
|
||||
add a set of options BF_3RDPARTY, BF_3RDPARTY_INC, BF_3RDPARTY_LIB,
|
||||
BF_3RDPARTY_LIBPATH:
|
||||
|
||||
1) Add all mentiond options to all (platform)-config.py
|
||||
files. WITH_BF_NEWLIB is a boolean option ('true', 'false'),
|
||||
the rest are strings with paths and library names. See the
|
||||
OpenEXR options for example.
|
||||
|
||||
2) Add all options to the argument checking function
|
||||
validate_arguments() in btools.py. See again OpenEXR options
|
||||
for example.
|
||||
|
||||
3) Add all options to the option reading function read_opts()
|
||||
in btools.py. See again OpenEXR options for example. All default
|
||||
values can be empty, as the actual default values are in the
|
||||
(platform)-config.py files.
|
||||
|
||||
4) Add BF_3RDPARTY_LIB to the function setup_syslibs()
|
||||
and BF_3RDPARTY_LIBPATH to the function setup_staticlibs()
|
||||
in Blender.py
|
||||
|
||||
At this stage we have prepared all option setting and linking needs,
|
||||
but we still need to add in the compiling of the 'newlib'.
|
||||
|
||||
5) Create a SConscript in $BLENDERHOME/source/blender/newlib. Look
|
||||
at ie. $BLENDERHOME/source/blender/src/SConscript for
|
||||
template. The new SConscript will register the new library
|
||||
like so:
|
||||
|
||||
env.BlenderLib(libname='newlib', sources=sourcefiles, includes=incs) # the rest of the arguments get defaults = empty lists and values
|
||||
|
||||
6) Edit $BLENDERHOME/source/blender/SConscript with the following
|
||||
addition:
|
||||
|
||||
if env['WITH_BF_NEWLIB'] == 1:
|
||||
SConscript(['newlib/SConscript'])
|
||||
|
||||
After this you can see if this works by trying to build:
|
||||
|
||||
% scons WITH_BF_NEWLIB=1 # build with newlib
|
||||
% scons WITH_BF_NEWLIB=0 # disable newlib
|
||||
|
||||
This is all what should be needed. Changing the library name doesn't
|
||||
need changes elsewhere in the system, as it is handled automatically
|
||||
with the central library repository.
|
||||
|
||||
Enjoy the new system!
|
||||
|
||||
/Nathan Letwory (jesterKing)
|
||||
179
doc/blender-scons.txt
Normal file
179
doc/blender-scons.txt
Normal file
@ -0,0 +1,179 @@
|
||||
$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).
|
||||
|
||||
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.
|
||||
|
||||
|
||||
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)
|
||||
Loading…
Reference in New Issue
Block a user