From BlenderWiki

Jump to: navigation, search

Introduction

This page is meant to provide new developers with information about how the Blender development process works, where to find info and how to determine which parts of Blender are safe to work on (Blender is currently being slowly refactored and rewritten, and as such some parts are marked off-limits until their rewrite has happened).

You can find additional info at Get Involved.

Communication Information

Most communication happens on the mailing lists at bf-committers (developers talk), bf-python (python scripts talk) and bf-funboard (new features talk), and on the #blendercoders IRC channel hosted by irc.FreeNode.net.

Other communication arenas include the Developer Forums, related mailing lists, and related IRC channels such as #verse, #crystalspace, #blender, #blendercompilers and other such channels.

No spamming or flaming on the lists or irc channel is allowed. Please stay on topic in the lists, and follow good net etiquette.

Do not send html messages to the mailing lists. Html messages can be contain a variety of security problems (like the common practice of including hidden image tags that link to a special, per-email-address url, and then watching the url to confirm that an email address is "live") and as such tend to be mistrusted by many people.

Sunday IRC Meeting

If you want to start developing in Blender you will have lots of startup questions. While you can always ask them in #blendercoders each day of the week, you can also attend a monthly NewDev meeting. The meeting is held on the first Sunday of every month, and starts an hour before the regular developer meeting. Visit the link above for more info and the agenda, and history of previous meetings. Add you item to the agenda by editing the appropriate wiki page.

For regular developers, every Sunday there is a development meeting in #blendercoders. It takes place at GMT 15:00, see the Sunday Meeting Agenda page for more information (including meeting notes of past meetings).
The Sunday meeting is where all the developers bring each other up to speed on their various projects and review pending patches on the blender patch tracker.

During the meeting, stay on topic. If you want to seek approval for project ideas, or contact another developer, log in before the meeting, hang around after or message another developer personally during meeting time.

Getting Started

Thank you for your interest in building Blender, and possibly becoming a Blender developer. Building Blender is fun!

These official build instructions assume you are a knowledgeable computer user--- if not a developer outright. As a result, they limit step-by-step instructions as found in most commercial manuals. Instead, you should regard these instructions as a crib-sheet for building blender. Brain not included, so bring your brain.

Building blender is much like building other Open Source software--- the key differences are the kinds of build systems supported. The basic principles are the same, and the knowledge you gain by toughing it out and building blender will carry forward to many other Open Source projects.

See [[ http://wiki.blender.org/index.php/BlenderDev/Blender2.5/QuickStartDevelopers the Quick Start for Developers Guide]] for getting started.

Installing tools and source code dependencies

The tools necessary for building blender vary based on your chosen Build Path. Have your platform and build system in mind as you proceed.

Great care has been taken by blender developers to ensure that blender is portable C code. Most of the blender core is written in C, using an object oriented programming system called BlenderDev/OOPS. Library API's are always exposed using C, even if the library is written in C++. Frequently, but not always, new functionality is written using Python (modifying the python API by wrapping the C if necessary) and then after working out the usability issues and testing the functionality out--- it is ported to C for speed. In summary, as a blender developer you will need a full development environment for C, C++, and Python.

Installing tools

Install a C/C++ compiler, debugger, editor, performance tools, etc... choose your platform below to get started:

  • Linux usually includes a full development environment based on GCC. Do yourself a favor and rely on the package manager for your distribution to install GCC et. al.
  • Mac OS X development tools are most easily installed from the Install DVDs that shipped with your Mac.
    • Insert the first Install DVD and launch the Mac OS X installer. After rebooting, choose Customize... then select Developer Tools to install the Developer Tools. If you plan to compile Universal Binaries (right now, the Blender Foundation does not support Universal Binaries because of the increased download size), but if you want to learn how anyway, be certain to install the 10.4u SDK or later.
    • OR download the XCode Tools from Apple Warning, this is a big download: ~1GiB! You will need to sign up as a ADC member prior to the download. Membership is free.
  • Windows development tools come in two major flavors, Free Open Source, and Free & Non-Free Closed Source.
    • Free tools (read GCC) for Windows:
      • MinSYS + MinGW Provides a native minimal Unix-like system for Windows. Produces native Windows binaries. Can be used to produce native Windows binaries for everything except for Windows OS Drivers.
      • Cygwin Gives an "emulated" Unix-like system for Windows. Produces binaries linked against cygwiin.dll (thus, these are non-native). Using Cygwin to create distributable binaries is discouraged.
    • Non-Free Closed Source for Windows:
      • Visual Studio (.NET, 2005, 2003, 6) MSVC If you have an MSDN subscription, that you have already purchased, start here.
      • Any other C/C++ compiler (Intel, IBM, Metrowerks, etc...) --- you know what you are doing, and why.
    • "Free" Closed Source:

After you have installed a full C/C++ development environment, install the following:

  • A full installation of Python (blender ships with Python, but to compile blender for releases, you will probably need to install Python.)
  • One or all of the build tools supported by the blender developers:
    • GNU Make using the trusty NaN Makefiles.
    Most all operating systems have gnumake, except Windows of course.
    Put build customizations in bf-blender/blender/user-def.mk
    • Scons using the SConscript and SConstruct files.
    Few operating systems ship with SCons.
    Put build customizations in bf-blender/blender/user-config.py
    • CMake using the CMakeList.txt files.
    Few operating systems ship with CMake.
    Customize the build using ccmake, OR edit bf-blender/blender/CMakeCache.txt or specify them on the command line.

Installing dependencies

While the binary dependencies in the bf-blender/lib tree are maintained for your convenience, some of the libraries have been heaviliy patched. As a result, you should use the bf-blender/lib tree whenever possible. Build Path specific dependency information is included in the Building Blender part of this guide.

Note
You should try to only checkout the folder in bf-blender/lib corresponding to your operating system environment, for example bf-blender/lib/windows. You should still preserve the lib/[folder] path structure, unless you are building with scons, in which case you can manually specify the path to the libs by overriding LCGDIR in your user-config.py.


ABI shift warning!

Note: Between GCC 3.1 and GCC 3.3, and between GCC 3.3 and GCC 4.0, the application binary interface (ABI) for C++ programs changed. This requires that all C++ libraries you link against with blender MUST be compiled with the same version of GCC that you are using to compile blender. Most binary Linux distributions will handle this for you. Mac OS X users need to be aware, and use caution when linking with the bf-blender/lib tree. Windows users compiling with GCC may also need to exercise care.

  • Linux users will probably need to install a large list of development packages using the system's package manager (Apt, RPM, etc.). These packages depend on the distribution you're using, your version of libc, etc...
  • Mac OS X users will need to download and install some packages in /usr/local/ (or /opt/local or /sw/usr/local/) until the bf-blender/lib directory offers all of the dependencies needed for Mac OS X. You can use MacPorts (recommended) or Fink, but these options are not automatically supported in all three build systems.
  • IMPORTANT as noted by Apple: Between GCC 3.1 and GCC 3.3, and between GCC 3.3 and GCC 4.0, the application binary interface (ABI) for C++ programs changed for Mac OS X. It is extremely important to recompile all code, libraries and frameworks exporting a C++ interface. For the purposes of blender, do not link C++ objects compiled with GCC 3.3 or 3.1 against objects compiled with the GCC 4.0. Errors may not appear until runtime, even if the link succeeds.

  • Windows users will need to install a wide variety tools and subsystems. Most dependencies for Windows are handled by the bf-blender/lib/windows directory (make sure to download to lib/windows, not windows, the directory structure is important for most build systems).

Downloading the blender source without SVN

To obtain the blender source without using SVN see the following links. Be aware that the blender source tarball including bf-blender/lib is larger than 120 MiB, so only download it if you must: Daily SVN Checkouts

blender.org Source Code Page

Downloading blender with SVN (preferred)

In general, you will want to use sources from SVN if you will be compiling blender. In the long run, SVN saves bandwidth for all by only downloading updates instead of the entire source tree. Most supported platforms come with svn on the command line, with the notable exception of Windows.

Using SVN

Please see http://www.blender.org/development/coding-guides/svn-checkout-and-usage/ . In case you need to access old CVS repository, instructions found at here may be helpful.

Building Blender

See [Building Blender]

Intro to the Development Process

Blender development is structured similarly to Python's BDFL model (BDFL stands for Benevolent Dictator For Life). The idea is that the project is managed by one man, in this case Ton Roosendaal, who delegates design decisions to a group of module owners, while still maintaining a veto right of what goes into Blender).

For a list of module owners, see [1].

Your First Project

Once you have blender compiled you're probably wondering where to start tinkering. If you are a Blender user then there is probably some niggling thing you would like to add or change. If you are new to Blender then you will need to take a look and see what you might work on.

There are no hard and fast rules about where to start, so find an area that interests you and start looking onto it.

Some hints for your first projects:

  • An area of interest (even better, an area of Blender you use)
  • Double check it is not already done.
  • It's best not to change Blender's file format (SDNA)
  • Don't choose a project that spans across many files and areas of Blender, since you may get bogged down trying to understand everything at once.
  • Make sure your project doesn't violate code marked for refactoring.

Here are some areas that can give you a foot in the door:

Small Features

Adding in small features is a good way to start getting your hands dirty, even if you dont make a patch to commit, it can evolve into something more useful, take a new direction, or spark interest in new areas to develop.

Bug Fixing

One of the easiest ways to get involved with coding Blender is by fixing bugs. Bug-fixing lets you focus on a small part of the Blender source rather than trying to understand it all at once. The list of current bugs is here. So pick an area of interest and start fixing! When you have got it, make a patch and submit it to the patch tracker as described here .

Python API

If you have used python and need to access data/functionality that is currently not available, then extending the python api can be a good place to start since there is a lot of example code and you can often start by copying functions and modifying them.

Guide to Developing Blender

Development process

Steps for getting a patch into Blender

  1. Find an area in Blender you want to improve upon.
    If you need inspiration, check Requests (barely up do date). You can also scan the forums on blender.org or blenderartists.org and the functionnalities mailing list
    Some people will do simple coding tests, to make sure what they want is feasible; others will do this later.
  2. Determine whether that area of the code is off-limits.
    (see Code Marked for Refactoring for a list of off-limits code).
  3. Find whoever "owns" the code and check if he agrees with your project.
    See the list of module owners to find who owns what. Generally the best idea is to talk to the owner(s) in #blendercoders, but new developers might want to email the mailing list instead.
  4. Post a design document on this wiki.
    Create a new page linked to BlenderDev/Current_Projects.
    To obtain wiki editing rights, follow instructions on the this page.
  5. Do the actual coding.
    See Coding Blender, below.
  6. Make a patch.
    See Using_Patches
    Making the patch isn't particularly hard, what makes this part annoying is
    a)the wait for the patch to be reviewed, which can take weeks if you push for it and months if you don't, and...
    b) the fact that the module owner may heavily modify your patch :)
    Keep in mind your patch may be rejected; although the reason for all the above steps is to hopefully make sure you never get to the coding stage if it's decided that your project isn't suitable in Blender (miscommunications between module owners and the BDFL can sometimes result in approved projects that should't have been approved, but this is pretty rare).

Release Process

So, assuming your patch has been approved and is integrated into SVN, congratulations! Now comes the release cycle. Up until this point you have probably been working with https://svn.blender.org/svnroot/bf-blender/trunk/ and with program source files on your local machine. There are two kinds of releases: "feature" releases and "bugfix" releases. The release type is designated by the release leader, and it is up to them to decide how to best handle the packaging and testing of the release. The release cycle is very open, but generally goes through two freezes:

  1. Code, Feature Freeze: code is frozen "as is" in a supposedly working state
  2. Bugfix freeze: any show-stopper bugs in the frozen code are fixed

After the bugfix freeze, the release candidates are built/packaged from SVN and made available for testing.

  • Generally, feature releases are built directly from the trunk.
  • For bugfix releases, a branch may be created off the trunk, something like https://svn.blender.org/svnroot/bf-blender/branches/blender-2.47/ and files will be moved over selectively, since work may be continuing in other areas toward the next feature release. If a branch is created, you need to ensure your code is indeed a bugfix, or if it is a new feature. If it is a bug fix, it should be copied over and you need to check the branch to ensure your code is there (if it was overlooked, bug a dev to move it over). If your code is a new feature, it may either have dependencies that prevent it from being moved, or may not be documented, or have other reasons why it should not go into the bugfix release.

Next comes the release candidates (rc's) where the code is compiled using make files and such. If you have a new file, it is possible your file is not listed in the make file, and thus is not in the "rc". Therefore, you need to download and test each rc to ensure your code is in there, and that there are not any last minute conflicts. These rc's are available from graphicall.org, and are platform-specific. So, you need to download and test as many platforms as you can, and network with friends that have the other platforms to test your code on their platform.

Hints for getting your patch reviewed and approved

Patches, whether for new features or bugfixes, get reviewed much quicker when they

  • are accompanied by a good description of what they do and if applicable what a user needs to do to use new features.
  • include a test script or .blend file to demonstrate the patch. You did test it right?
  • Make sure you create the patch against current cvs (do a cvs update before creating your patch).
  • are readable. Put some useful comments in your code. Code is read much more than it is written. Don't make people struggle to figure out what you are doing. Use the blender Style guide for your code. http://www.blender.org/cms/Coding_Style.141.0.html

Coding Blender

There's a lot of information on coding blender out there; see the below links. The most basic introduction to the code is to look at source/blender/src/space.c, which has most of the event handling functions (you can use grep or windows search to find the functions used in space.c).

Blender Development Guides and Standards

The Coding Blender section on Blender3d.org.

Hacker's Guide - Basic Information and Tutorials

Coding Tutorials

Code Marked For Refactoring

The following areas of Blender's codebase are "off-limits" until their refactoring is completed (this may not be a complete list).

The Event System