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