== 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.

2 files changed, 373 insertions, 0 deletions

diff --git a/doc/blender-scons-dev.txt b/doc/blender-scons-dev.txt
new file mode 100644
index 00000000000..9d2db77ebf4
--- /dev/null
+++ b/doc/blender-scons-dev.txt
@@ -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)
diff --git a/doc/blender-scons.txt b/doc/blender-scons.txt
new file mode 100644
index 00000000000..bc0237494dc
--- /dev/null
+++ b/doc/blender-scons.txt
@@ -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)