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