## Building Blender from source

This document describes the tools necessary to build Blender from source, either from cvs or from a source package. Building from cvs requires the use of more tools. While this may be a bit more troublesome than building from a source package, this may be necessary for some people. For example, when you want to build Blender for an unsupported platform or when you want to implement some new features to this exiting program.

This is a very early version of this document. This means that it is incomplete and that some procedures or concepts are not correct. Please keep this in mind when reading this.

## Getting the sources

The following paragraphs will describe how and where to get the sources needed for building Blender.

### Get the latest stable source package

Download a source tarball at the same place you got this document, or get it from http://www.blender3d.org/Download/?sub=Source

### Get the latest sources from CVS

CVS stands for Concurrent Versioning System. It is a software configuration tool that keeps the various source files in a central repository. CVS enables developers to quickly update to the latest state of the repository and commit changes. The tool keeps track of the changes between each version of a file. To get the current state of the repository, you don't need to have a username for accessing the sources. This feature is optional, but in an opensource development, it's almost a requirement. To commit changes to the repository, however, you need to have developer access. Since this document only describes how to get the latest state of the sources, the commit procedures are not described here. Should the CVS commit procedures and how to get developer access also be described here?

To get the latest state of the sources use:

`export CVSROOT=:pserver:anonymous@cvs.blender.org:/cvs01`

`cvs login`

password: Enter

`cvs -z3 co blender`

Please do not use a higher level of compression for accessing the Blender server.

If you already have a working set of files obtained from the server, you can use the `update` command to update the sources to the current state of the repository. `cd` to the blender source tree on your system and type in the following command:

`cvs -z3 update .`

## External libraries needed

Blender is a package that uses a lot of external packages for expanding its functionality. Each of these packages have, just as Blender, a history of changes. Newer versions of such a package will probably have more features and less known problems. As a developer it is exiting to work with the latest features available to get the most out of the tool. However, the number of developers out there is much lower than the number of end-users who are not interested in the latest feature, these users want an application that works. Since Blender has to run on multiple platforms, all those platforms have to have the same minimum functionality available in the external packages.

The table below displays the packages needed and the minimum version of those packages. Over time it is possible that those minimum versions are increased as the demand for the newer features is high. Are the versions listed below truly the minimum or can some versions even be lower? Also, is the list complete?

### Minimum version external libraries

Library | Version
--- | ---
glibc | 2.2.4
libjpeg | 6b
libpng | 1.0.14
libsdl | 1.0
libz | 1.1.4
mesa | 3.4.2
openAL | ??
openGL | 1.2
python | 2.0

Not all libraries apply to all platforms. The following table gives an overview of the currently supported platforms and the required libraries. An 'X' means that it is needed, a '-' means that it is not needed and an 'O' means that it is optional. Please check the table below.

### Platform dependent library requirements

Library | Linux | Windows | FreeBSD | IRIX | MacOS X
--- | --- | --- | --- | --- | ---
glibc | X | - | X | X | X
libjpeg | X | X | X | X | X
libpng | X | X | X | X | X
libsdl | O | O | O | O | O
libz | X | X | X | X | X
mesa | X | X | X | - | X
openAL | X | X | X | X | X
openGL | - | - | - | X | -
python | X | X | X | X | X

## Tools needed

Having the necessary libraries installed and the Blender sources downloaded to your system means that you're now able to build Blender. The entire build process requires some tools to be available on your system. In the table below, the list of tools along with the minimum version is shown. The third column shows if the tool is required for CVS only ('X'). If the tool is not required for a source package build, a '-' is shown. Is the table below complete and are the versions listed truly the minimum versions needed to build Blender?

### Minimum version tools

Tool | Version | CVS | Note
--- | --- | --- | ---
autoconf | 2.53 | X
automake | 1.6.2 | X
cvs | 1.11.1p1 | X
docbook | 3.1 | O
doxygen | ?? | O
gawk | 3.1.0 | X
gcc | 2.96 | -
gettext | 0.11 | -
gmake | 3.79.1 | -
m4 | 1.4 | X
sed | 3.02 | X
sh | 2.05.1 | -
Visual C++ | 6.0 SP5 | - | Windows only

Python is not included in this table although it is used to build Blender. The reason that it is not included is because Python is also needed as an external library and thus has to be installed already as has been written in the previous section.

## Building Blender

The paragraphs that follow will describe a generic build process that applies to most platforms. If a step is not applicable for a platform or the procedure is different, it is noted. For the Windows build, refer to the Windows specific section.

The Windows specific parts have not been written yet...

### Bootstrapping

Bootstrapping the Blender sources is needed to create an overall `configure` script. In a source package the `configure` script is included and therefore the bootstrapping step can be skipped. In the root of the Blender source tree, a `bootstrap` script is located. This script calls the `aclocal`, `automake` and `autoconf` tools to create from the various input files the necessary Makefile.in files and the `configure` script. To generate the `configure` script, execute the following command:

`./bootstrap`

I get an undefined AC_PROG_LIBTOOL message. What do I need to do to fix this?

Copy the `acinclude.m4` from `/usr/local/share/libtool/libltdl/` into the root of your blender source directory.

### Running configure

Running the `configrue` script, will generate the Makefiles needed to build Blender. To keep the blender source tree as clean as possible, it is recommended to run configure from another directory. From the root of your Blender source tree do:

`mkdir ../build_blender`

`cd ../build_blender`

`../blender/configure`

It is possible to pass some flags to the configure script to customize your Blender build.

TODO: add the description of all possible flags to this section.

### Compile the sources

TODO: Write something useful here...

### Installing Blender

TODO: Write something useful here...

### Building Blender on Windows

TODO: Write something useful here...