diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/build_systems/scons-dev.txt | 193 | ||||
| -rw-r--r-- | doc/build_systems/scons.txt | 227 |
2 files changed, 0 insertions, 420 deletions
diff --git a/doc/build_systems/scons-dev.txt b/doc/build_systems/scons-dev.txt deleted file mode 100644 index 9ca072c38c5..00000000000 --- a/doc/build_systems/scons-dev.txt +++ /dev/null @@ -1,193 +0,0 @@ - - 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 - * linux - * 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/build_files/scons/tools, with - Blender.py defining the bulk of the functionality. btools.py has some - helper functions, and bcolors.py is for the terminal - colors. 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 deleted file mode 100644 index e3438f1fe04..00000000000 --- a/doc/build_systems/scons.txt +++ /dev/null @@ -1,227 +0,0 @@ - - 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. - - For build instructions, including dependencies, consult the appropriate - section for your platform at - http://wiki.blender.org/index.php/Dev:Doc/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 color 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/build_files/scons/config/(platform)-config.py. See the next - section of this document for how to customize these paths. 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/build_files/scons/config. Your platform specific defaults are - in (platform)-config.py, where platform is one of: - - - linux, 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 build_files/scons/config/(platform)-config.py that you - want to change. Don't copy the entire file (unless explicitly stated in - the configuration file), because you may not get updated options you don't - change yourself, which may result in build errors. You should NEVER have - to modify $BLENDERHOME/build_files/scons/config/(platform)-config.py. - - 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). - - 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 colors can be changed: - - % python scons\scons.py BF_FANCY=0 - - This will disable the use of colors. - - % 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) |