== docs ==

- moved files in proper directories and adapted paths where needed
- deleted doc/oldbugs.txt (asked confirmation to jesterking a week ago in irc)
- still working on doxygen files, for now I'll leave them in doc/
- NOTE: while checking if other files were referring to these files, I noted that
  "GPL-license.txt" is also used in the files below:
    - release/windows/installer/00.sconsblender.nsi
    - release/windows/specific.sh
  but these files should't be affected by this commit, but please check :) 

4 files changed, 704 insertions, 0 deletions

diff --git a/doc/build_systems/README.windows-gcc b/doc/build_systems/README.windows-gcc
new file mode 100644
index 00000000000..78018eabbc0
--- /dev/null
+++ b/doc/build_systems/README.windows-gcc
@@ -0,0 +1,123 @@
+An updated version of this guide can be found at:
+
+http://www.blender3d.org/cms/Building_with_Cygwin.524.0.html
+
+Introduction
+------------
+
+Here are some basic instructions for building
+blender for windows using gcc under cygwin.
+Please note that the resulting executable does not
+depend on cygwin and can be distrubuted to machines
+that don't have cygwin installed.
+
+The instructions are:
+
+1. Download cygwin (www.cygwin.com) and use the setup program
+   to install packages for gcc, gcc-mingw, gcc-g++, w32api, make, cvs,
+   python, perl, gettext, and gettext-devel (and maybe others... the 
+   dependency list is bound to change over time and hopefully these 
+   instructions will keep up with the changes). All of the following
+   commands will be entered at the cygwin prompt so launch
+   cygwin now.
+
+2. Create a directory to put your sources and then enter that
+   directory, e.g.:
+     mkdir bf-blender
+     cd bf-blender
+
+   *********WARNING: if the directory path you are in contains a space in
+   it you will get errors in trying to compile the code.  Change directorys
+   to a one that does not contain a space in the path before creating the
+   above directory *********
+
+
+Please note that a backslash at the end of a line in the following 
+means that the command spans two lines. If you wish to type the command as 
+one line, exclude the '\'.
+
+3. Checkout the blender module from the bf-blender tree using cvs 
+   (use password anonymous):
+     cvs -d:pserver:anonymous@cvs.blender.org:/cvsroot/bf-blender login
+     cvs -z3 -d:pserver:anonymous@cvs.blender.org:/cvsroot/bf-blender \
+          co blender
+
+4. Checkout the lib/windows module from bf-blender using cvs:
+     cvs -z3 -d:pserver:anonymous@cvs.blender.org:/cvsroot/bf-blender \
+          co lib/windows
+
+5. Enter the newly created blender directory:
+     cd blender
+
+6. To prepare the build system to use only the free tools we must
+   set some environment variables. This is done by creating a
+   file called "user-def.mk" in the blender directory and
+   inserting the following line with notepad or your favorite
+   text editor:
+       export FREE_WINDOWS=true
+
+   The quickest way to do this though is to issue the following
+   command:
+      echo 'export FREE_WINDOWS=true' > user-def.mk
+
+7. Time to build... issue the command:
+     make
+
+8. Wait for it to finish (there is this mysterious place called 
+   'outside' that I am told is nice to go to while waiting for a 
+   compile to finish).
+
+9. After it finishes compiling, if you would like to run your freshly compiled
+   blender, type make release.  Then change directorys to obj/233.a/ and move
+   the zip file to where you want to use it, unzip the file, enter the directory
+   and run your brand new blender.
+
+
+Getting Help
+------------
+If you have problems, come by #blendercompilers on irc.freenode.net
+or post questions to the "Compiling, Libraries, Modules" forum
+at www.blender.org. There is also the very useful bf-committers 
+mailing list, what you can subscribe to here:
+
+http://www.blender.org/mailman/listinfo/bf-committers
+(as a bonus you can get info about the most recent features that
+are coming down the pipe ...)
+
+This said, the most common fix to a problem will
+probably involve installing an additional cygwin package,
+so keep that cygwin setup program close by ...
+
+Some final notes
+----------------
+
+- The build will take a long time, even on a fast machine
+  (a clean build takes almost an hour on my Athlon 1800+
+  based laptop).
+- If the build is successful you will find it has created
+  the program obj/windows/bin/blender.exe
+- The executable generated by gcc will generally be slower
+  that an msvc++ generated executable at rendering, but the 
+  OpenGL speed should be about the same.
+- Sound is disabled
+- If you want to clean your sources issue a 'make clean'
+  in the top blender directory.
+- If you want to update your sources when somebody has
+  added a new awesome feature, you will want to go to the
+  topmost blender directory and issue the following command:
+      cvs -z3 update -P -d
+  It would probably be best to clean your sources before
+  re-building (see previous note).
+- This is a work in progress, so some things may not be working
+  right or it may not support all of the cutting edge features.
+- Want to make a fancy zipped up blender package to give
+  to your buddies? Try "make release" ... read the output
+  to find out where the zip file was placed (note: you will
+  probably need the zip/unzip packages from cygwin to do
+  this).
+- You can make a debug executable using 'make debug'. The
+  debug executable will be larger and slower that the
+  regular executable, but when used with the gnu debugger
+  (gdb) it can help debug a blender problem (for example,
+  it can locate the line of code that caused blender to
+  crash).
diff --git a/doc/build_systems/cmake.txt b/doc/build_systems/cmake.txt
new file mode 100644
index 00000000000..a49ff629b5b
--- /dev/null
+++ b/doc/build_systems/cmake.txt
@@ -0,0 +1,156 @@
+$Id$
+
+    Blender CMake build system
+    ============================
+
+    Contents
+    ---------------
+
+    1. Introduction
+    2. Obtaining CMake
+    3. Obtaining Dependencies
+    4. Deciding on a Build Environment
+    5. Configuring the build for the first time
+    6. Configuring the build after CVS updates
+    7. Specify alternate Python library versions and locations
+
+
+    1. Introduction
+    ---------------
+
+    This document describes general usage of the new CMake scripts. The
+    inner workings will be described in blender-cmake-dev.txt (TODO).
+
+    2. Obtaining CMake
+    ------------------
+
+    CMake for can either be downloaded using your favorite package manager 
+    or is also available from the CMake website at http://www.cmake.org 
+    The website also contains some documentation on CMake usage but I found
+    the man page alone pretty helpful. 
+
+    3. Obtaining Dependencies
+    -------------------------
+
+    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.
+
+    4. Deciding on a Build Environment
+    ----------------------------------
+
+    To build Blender with the CMake scripts you first need to decide which
+    build environment you feel comfortable with. This decision will also be
+    influenced by the platform you are developing on. The current implementation
+    have been successfully used to generate build files for the following 
+    environments:
+
+    1. Microsoft Visual Studio 2005. There is a free version available
+       at http://msdn.microsoft.com/vstudio/express/visualc/.
+
+    2. Xcode on Mac OSX
+
+    3. Unix Makefiles (On Linux and Mac OSX): CMake actually creates make 
+       files which generates nicely color coded output and a percentage 
+       progress indicator.
+
+
+    5. Configuring the build for the first time
+    -------------------------------------------
+
+    CMake allows one to generate the build project files and binary objects
+    outside the source tree which can be pretty handy in working and experimenting
+    with different Blender configurations (Audio/NoAudio, GameEngine/NoGameEngine etc.)
+    while maintaining a clean source tree. It also makes it possible to generate files
+    for different build systems on the same source tree. This also has benefits for 
+    general CVS management for the developer as patches and submit logs are much cleaner.
+
+    Create a directory outside the blender source tree where you would like to build
+    Blender (from now on called $BLENDERBUILD). On the commandline you can then run
+    the cmake command to generate your initial build files. First just run 'cmake' which
+    will inform you what the available generators are. Thn you can run 
+    'cmake -G generator $BLENDERSOURCE' to generate the build files. Here is an example 
+    of all this for Xcode:
+
+        % mkdir $BLENDERBUILD
+        % cd $BLENDERBUILD
+        % cmake
+
+		...
+		...
+		--version [file]            = Show program name/version banner and exit.
+
+		Generators
+
+		The following generators are available on this platform:
+		  KDevelop3                   = Generates KDevelop 3 project files.
+		  Unix Makefiles              = Generates standard UNIX makefiles.
+		  Xcode                       = Generate XCode project files.
+
+
+
+        % cmake -G Xcode $BLENDERSOURCE
+		...
+		...
+		-- Configuring blender
+		-- Configuring blenderplayer
+		-- Configuring done
+		-- Generating done
+		-- Build files have been written to: $BLENDERBUILD 
+
+    This will generate the build files with default values. Specific features can
+    be enabled or disabled by running the ccmake "GUI" from $BLENDERBUILD as follows:
+
+        % ccmake $BLENDERSOURCE
+
+    A number of options appear which can be changed depending on your needs and
+    available dependencies (e.g. setting WITH_OPENEXR to OFF will disable support
+    for OpenEXR). It will also allow you to override default and detected paths 
+    (e.g. Python directories) and compile and link flags. When you are satisfied
+    used ccmake to re-configure the build files and exit.
+
+    It is also possible to use the commandline of 'cmake' to override certain
+    of these settings. 
+
+    6. Configuring the build after CVS updates
+    ------------------------------------------
+
+    The $BLENDERBUILD directory maintains a file called CMakeCache.txt which 
+    remembers the initial run's settings for subsequent generation runs. After
+    every CVS update it may be a good idea to rerun the generation before building
+    Blender again. Just rerun the original 'cmake' run to do this, the settings
+    will be remembered. For the example above the following will do after every
+    'cvs up':
+
+        % cmake -G Xcode $BLENDERSOURCE
+
+    7. Specify alternate Python library versions and locations
+    ----------------------------------------------------------
+    
+    The commandline can be used to override detected/default settings, e.g:
+ 
+    On Unix: 
+      cmake -D PYTHON_LIB=/usr/local/lib/python3.1/config/libpython3.1.so -D PYTHON_INC=/usr/local/include/python3.1 -G "Unix Makefiles" ../blender
+    On Macs: 
+      cmake -D PYTHON_INC=/System/Library/Frameworks/Python.framework/Versions/3.1/include/python3.1 -G Xcode ../blender
+
+    Mote that this should only be needed once per build directory generation because it will keep the overrides in CMakeCache.txt for subsequent runs.
+
+
+
+    To be continued...
+
+    TODO's
+    ------
+
+    1. Get CMake to create proper distribution directories for the various platforms
+       like scons does.
+    2. Investigate the viability of using CPack to package installs automatically.
+    3. Refine this document and write detailed developer's document.
+    4. Make sure all options (ffmpeg, openexr, quicktime) has proper CMake support
+       on the various platforms.    
+
+    /Jacques Beaurain (jbinto)
+
diff --git a/doc/build_systems/scons-dev.txt b/doc/build_systems/scons-dev.txt
new file mode 100644
index 00000000000..d13ea7c036f
--- /dev/null
+++ b/doc/build_systems/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_PRIORITYLIST=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_PRIORITYLIST 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/build_systems/scons.txt b/doc/build_systems/scons.txt
new file mode 100644
index 00000000000..b4d9a905885
--- /dev/null
+++ b/doc/build_systems/scons.txt
@@ -0,0 +1,231 @@
+$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 scons-dev.txt.
+
+    Building Blender
+    ----------------
+
+    To build Blender with the SCons scripts you need a full Python
+    install, version 2.4 or later (http://www.python.org). We already provide
+    a scons-local installation, which can be found in the scons/ subdirectory.
+    This document uses the scons-local installation for its examples.
+
+    Check from the page
+    http://www.blender.org/development/building-blender/getting-dependencies/
+    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, start the SCons entry script on Windows (will be used for the remainder
+    of this document):
+
+        % python scons\scons.py
+
+    On a Unix-compatible system it would be
+
+        % python ./scons/scons.py
+
+    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. The BF_DOCDIR is
+    used to generate Blender Python documentation files to. These
+    variables 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.
+
+    If you want to create the installer package of Blender on Windows you'll
+    need to install nullsoft scriptable install system from http://nsis.sf.net.
+    As an extra dependency, you need the MoreInfo plugin too. The creation of
+    the installer is tied into the build process and can be triggered with:
+
+        % python scons\scons.py nsis
+
+
+    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 file called  $BLENDERHOME/user-config.py, and copy
+    settings from the config/(platform)-config.py that you want to change. Don't
+    copy the entire file (unless explicitely stated in the configuration file),
+    because you may not get updated options you don't change yourself, which may
+    result in build errors.
+
+    You can use BF_CONFIG argument to override the default user-config.py
+    check. This is just like the user-config.py, but just with another name:
+
+        % python scons\scons.py BF_CONFIG=myownsettings
+
+    If you want to quickly test a new setting, you can give the option
+    also on the command-line:
+
+        % python scons\scons.py 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:
+
+        % python scons\scons.py -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).
+
+    NOTE: The best way to avoid confusion is the
+    copy $BLENDERHOME/config/(platform)-config.py to
+    $BLENDERHOME/user-config.py. You should NEVER have to modify
+    $BLENDERHOME/config/(platform)-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:
+
+        % python scons\scons.py BF_FANCY=0
+
+    This will disable the use of colours.
+
+        % python scons\scons.py 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.
+
+    Compiling Only Some Libraries
+    -----------------------------
+    
+    Our implementation now has support for specifying a list of libraries that are
+    exclusively compiled, ignoring all other libraries.  This is invoked 
+    with the BF_QUICK arguments; for example:
+    
+        % python scons\scons.py BF_QUICK=src,bf_blenkernel
+    
+    Note that this not the same as passing a list of folders as in the 
+    makefile's "quicky" command.  In Scons, all of Blender's code modules
+    are in their own static library; this corresponds to one-lib-per-folder 
+    in some cases (especially in blender/source/blender).
+    
+    To obtain a list of the libraries, simple fire up scons and CTRL-C out once 
+    it finishes configuring (and printing to the console) the library list.
+    
+    Compiling Libraries With Debug Profiling
+    ----------------------------------------
+    
+    Scons has support for specifying a list of libraries that are compiled
+    with debug profiling enabled.  This is implemented in two commands:
+    BF_QUICKDEBUG which is a command-line argument and BF_DEBUG_LIBS, which goes
+    in your user-config.py
+    
+    BF_QUICKDEBUG is similar to BF_QUICK:
+    
+        % python scons\scons.py BF_QUICKDEBUG=src,bf_blenkernel,some-other-lib
+    
+    To use BF_DEBUG_LIBS, put something like the following in you user-config.py:
+    
+        BF_DEBUG_LIBS = ['bf_blenlib', 'src', 'some_lib']
+        
+    For instructions on how to find the names of the libraries (folders) you 
+    wish to use, see the above section.  Note that the command BF_DEBUG 
+    (see below) will override these settings and compile ALL of Blender with
+    debug symbols.  Also note that BF_QUICKDEBUG and BF_DEBUG_LIBS are combined;
+    for example, setting BF_QUICKDEBUG won't overwrite the contents of BF_DEBUG_LIBS.
+
+    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
+
+        % python scons\scons.py BF_TOOLSET=msvc
+        % python scons\scons.py BF_TOOLSET=mingw
+
+    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:
+
+        % python scons\scons.py
+
+    Build Blender, but disable OpenEXR support:
+
+        % python scons\scons.py WITH_BF_OPENEXR=0
+
+    Build Blender, enable debug symbols:
+
+        % python scons\scons.py BF_DEBUG=1
+
+    Build Blender, install to different directory:
+
+        % python scons\scons.py BF_INSTALLDIR=../myown/installdir
+
+    Build Blender in ../myown/builddir and install to ../myown/installdir:
+
+        % python scons\scons.py BF_BUILDDIR=../myown/builddir BF_INSTALLDIR=../myown/installdir
+
+    Clean BF_BUILDDIR:
+
+        % python scons\scons.py clean
+
+    /Nathan Letwory (jesterKing)