1
$Id: blender-scons-dev.txt,v 1.2 2006/03/09 23:48:56 jesterking Exp $
4
Internals of Blenders SCons scripts
5
===================================
9
This document describes the architecture of the SCons scripts for
10
Blender. An overview of available functionality and how to modify,
11
extend and maintain the system.
15
This document is for developers who need to modify the system,
16
ie. add or remove new libraries, add new arguments for SCons, etc.
18
Files and their meaning
19
-----------------------
21
The main entry point for the build system is the SConstruct-file in
22
$BLENDERHOME. This file creates the first BlenderEnvironment to work
23
with, reads in options, and sets up some directory structures. Further
24
it defines some targets.
26
Platform-specific configurations are in $BLENDERHOME/config. The
27
filenames have the form (platform)-config.py, where platform one of:
34
The user can override options by creating a file
35
$BLENDERHOME/user-config.py. It can have any option from
36
(platform)-config.py. Options in this file will override the platform
39
Much of the actual functionality can be found in the python scripts
40
in the directory $BLENDERHOME/tools, with Blender.py defining the
41
bulk of the functionality. btools.py has some helper functions, and
42
bcolors.py is for the terminal colours. mstoolkit.py and crossmingw.py
43
are modules which set up SCons for the MS VC++ 2003 toolkit and
44
the cross-compile toolset for compiling Windows binaries on Linux
45
respectively. Note: the cross-compile doesn't work yet for Blender,
46
but is added in preparation for having it work in the distant future.
51
The module Blender.py implements a BlenderEnvironment class, derived
52
from the SConsEnvironment of SCons. This is done to wrap some often
53
used functionality. The BlenderEnvironment offers two important
54
wrappers: BlenderProg() and BlenderLib(). The first one is used to
55
specify a binary to be built, the second one is used to specify what
56
static library is built from given sources.
58
Build a static library called "somelib". The system handles library
59
pre- and suffixes automatically, you don't need to bother yourself
62
env = BlenderEnvironment(ENV = os.environ) # create an environment
63
env.BlenderLib(libname="somelib", sources=['list.c','with.c','sources.c'],
64
includes=['/list/with/include/paths', '.', '..'],
65
defines=['LIST_WITH', 'CPP_DEFINES', 'TO_USE'],
66
libtype=['blender', 'common'] # this is a list with libtypes. Normally you don't
67
# need to specify this, but if you encounter linking
68
# problems you may need this
69
priority=[10, 20] # Priorities, list as long as libtype, priority per type
70
compileflags=['/O2'] # List of compile flags needed for this particular library.
71
# used only in rare cases, like SOLID, qhull and Bullet
74
There should be no need to ever add an extra BlenderProg to the
75
existing ones in SConstruct, see that file for its use, and Blender.py
76
for its implementation.
78
The new system works so that using these wrappers, has all libraries
79
(and programs) register with a central repository. This means that
80
adding a new library is as easy as just creating the new SConscript
81
and making sure that it gets called properly. Linking and such will
82
then be handled automatically.
84
If you want that adding new source files for a certain library
85
is handled automatically, you can use the Glob() function from
86
the BlenderEnvironment to create lists of needed files. See
87
$BLENDERHOME/source/blender/src/SConscript for an example. Keep in
88
mind that this will add any new file that complies to the rule given
89
to the Glob() function. There are a few (external) libraries with
90
which this can't be used, because it'd take files that shouldn't be
91
compiled, and create subsequentially problems during the linking stage
92
(like SOLID, qhull, Bullet).
94
Linking order and priorities
95
----------------------------
97
As shown above, you can give a library a priority in a certain
98
group. If you need to make sure that a Blender library is linked
99
before or after another one, you can give it a priority. To debug
100
the priorities us BF_PRIORITYLIST=1 on the command-line while running
103
% scons BF_PRIORITYLIST=1
105
This will give a list with values suggested by the system. Make
106
changes to all SConscripts in question to reflect or change the
107
values given by this command. ALWAYS check this after adding a new
108
internal, external library or core library, and make sure there are
109
sane values. You can use large and negative numbers to test with,
110
but after you've got a working linking order, do change the system
111
to reflect BF_PRIORITYLIST values.
113
Also, if you find that a library needs to be given multiple times to
114
the linker, you can do that by giving a python list with the names
115
of the available library types. They are currently:
117
B.possible_types = ['core', 'common', 'blender', 'intern',
118
'international', 'game', 'game2',
119
'player', 'player2', 'system']
121
More groups can be added, but that should be carefully considered,
122
as it may lead to large-scale changes. The current amount of libraries
125
The central repository is utilised in the SConstruct in two
126
ways. Firstly, it is used to determine the order of all static
127
libraries to link into the main Blender executable. Secondly, it
128
is used to keep track of all built binaries and their location,
129
so that they can be properly copied to BF_INSTALLDIR.
131
The libraries can be fetched in their priority order with
132
create_blender_liblist from Blender.py, see the SConstruct on how
135
The program repository is the global list program_list from
136
Blender.py. See SConstruct for its usage.
139
Adding a new option and libraries
140
---------------------------------
142
Lets say we want to add WITH_BF_NEWLIB, which will
143
enable or disable a new feature library with sources in
144
$BLENDERHOME/source/blender/newlib. This 'newlib' needs external
145
headers from a 3rd party library '3rdparty'. For this we want to
146
add a set of options BF_3RDPARTY, BF_3RDPARTY_INC, BF_3RDPARTY_LIB,
149
1) Add all mentiond options to all (platform)-config.py
150
files. WITH_BF_NEWLIB is a boolean option ('true', 'false'),
151
the rest are strings with paths and library names. See the
152
OpenEXR options for example.
154
2) Add all options to the argument checking function
155
validate_arguments() in btools.py. See again OpenEXR options
158
3) Add all options to the option reading function read_opts()
159
in btools.py. See again OpenEXR options for example. All default
160
values can be empty, as the actual default values are in the
161
(platform)-config.py files.
163
4) Add BF_3RDPARTY_LIB to the function setup_syslibs()
164
and BF_3RDPARTY_LIBPATH to the function setup_staticlibs()
167
At this stage we have prepared all option setting and linking needs,
168
but we still need to add in the compiling of the 'newlib'.
170
5) Create a SConscript in $BLENDERHOME/source/blender/newlib. Look
171
at ie. $BLENDERHOME/source/blender/src/SConscript for
172
template. The new SConscript will register the new library
175
env.BlenderLib(libname='newlib', sources=sourcefiles, includes=incs) # the rest of the arguments get defaults = empty lists and values
177
6) Edit $BLENDERHOME/source/blender/SConscript with the following
180
if env['WITH_BF_NEWLIB'] == 1:
181
SConscript(['newlib/SConscript'])
183
After this you can see if this works by trying to build:
185
% scons WITH_BF_NEWLIB=1 # build with newlib
186
% scons WITH_BF_NEWLIB=0 # disable newlib
188
This is all what should be needed. Changing the library name doesn't
189
need changes elsewhere in the system, as it is handled automatically
190
with the central library repository.
192
Enjoy the new system!
194
/Nathan Letwory (jesterKing)
added
removed
doc/blender-scons-dev.txt
