doc/blender-scons-dev.txt

   1 $Id: blender-scons-dev.txt 7007 2006-03-09 23:48:56Z jesterking $
   2
   3
   4     Internals of Blenders SCons scripts
   5     ===================================
   6
   7     Scope
   8     ------
   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.
  12
  13     Audience
  14     --------
  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.
  17
  18     Files and their meaning
  19     -----------------------
  20
  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.
  25
  26     Platform-specific configurations are in $BLENDERHOME/config. The
  27     filenames have the form (platform)-config.py, where platform one of:
  28
  29         * darwin
  30         * linux2
  31         * win32-mingw
  32         * win32-vc
  33
  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
  37     defaults.
  38
  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.
  47
  48     BlenderEnvironment
  49     ------------------
  50
  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.
  57
  58     Build a static library called "somelib". The system handles library
  59     pre- and suffixes automatically, you don't need to bother yourself
  60     with these details:
  61
  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
  72                         )
  73
  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.
  77
  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.
  83
  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).
  93
  94     Linking order and priorities
  95     ----------------------------
  96
  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
 101     a build.
 102
 103     % scons BF_PRIORITYLIST=1
 104
 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.
 112
 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:
 116
 117         B.possible_types = ['core', 'common', 'blender', 'intern',
 118                             'international', 'game', 'game2',
 119                             'player', 'player2', 'system']
 120
 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
 123     should suffice.
 124
 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.
 130
 131     The libraries can be fetched in their priority order with
 132     create_blender_liblist from Blender.py, see the SConstruct on how
 133     it is used.
 134
 135     The program repository is the global list program_list from
 136     Blender.py. See SConstruct for its usage.
 137
 138
 139     Adding a new option and libraries
 140     ---------------------------------
 141
 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,
 147     BF_3RDPARTY_LIBPATH:
 148
 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.
 153
 154         2) Add all options to the argument checking function
 155         validate_arguments() in btools.py. See again OpenEXR options
 156         for example.
 157
 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.
 162
 163         4) Add BF_3RDPARTY_LIB to the function setup_syslibs()
 164         and BF_3RDPARTY_LIBPATH to the function setup_staticlibs()
 165         in Blender.py
 166
 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'.
 169
 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
 173         like so:
 174
 175             env.BlenderLib(libname='newlib', sources=sourcefiles, includes=incs) # the rest of the arguments get defaults = empty lists and values
 176
 177         6) Edit $BLENDERHOME/source/blender/SConscript with the following
 178         addition:
 179
 180             if env['WITH_BF_NEWLIB'] == 1:
 181                 SConscript(['newlib/SConscript'])
 182
 183     After this you can see if this works by trying to build:
 184
 185             % scons WITH_BF_NEWLIB=1  # build with newlib
 186             % scons WITH_BF_NEWLIB=0  # disable newlib
 187
 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.
 191
 192     Enjoy the new system!
 193
 194     /Nathan Letwory (jesterKing)