diff options
Diffstat (limited to 'doc/build_systems')
-rw-r--r-- | doc/build_systems/README.windows-gcc | 123 | ||||
-rw-r--r-- | doc/build_systems/cmake.txt | 156 | ||||
-rw-r--r-- | doc/build_systems/scons-dev.txt | 194 | ||||
-rw-r--r-- | doc/build_systems/scons.txt | 231 |
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) |