[Bf-committers] code restructure

[Ton Roosendaal]

Hi,

With doing so much code rehashing, I think it's good to share my view  
on a new structure too, to be executed after 2.3 is out.
This only applies for blender/source/blender.

0. Goal

- The code structure should reflect how Blender actually works, to make  
navigation & coding easier
- reveil weak spots in the structure, and document it for everyone to  
be aware of pitfalls
- add documentation as much as possible on the global structure,  
including how to add a new 'space editor' for example.

1. Definitions

- Library:
has no dependencies to other modules/libraries than what's default in  
the OS, Exceptions are possible like in libGL and libGLU (with the last  
one depending on the first). But that's a simple singular dependency.

To further classify, we have
- External Library
Like Python, OpenGL, ODE, FTGL, etc. Meaning, not developed by us.

- Internal Library
Like Imbuf, Ghost, Decimator, etc. Our stuff. Clean APIs with no  
dependencies to other Blender stuff.

- Module
Is like a library, but now with dependencies to:
   -> Libraries (internal and external)
   -> Framework
   -> Exceptional: to other Modules (well documented & minimal!)
Example: Render, Radiosity, etc.

- Framework
A special type of Module which links Modules together. Dependencies are  
allowed to Modules and Libraries and other FrameWorks. Spaghetti  
stuff...


2. General structure

A further rule is that dependencies have to stay in its own level, or  
go one level down. If not possible, handlers or callbacks should be  
made.

A diagram of Blender code levels can be like this (ascii art!)

------------------------------------------------------------
  (UI level)

           -------------   -------------    ------
           | edit mesh |   | Edit curve |   | etc |
           -------------   --------------   ------

           -------   ---------    -------   ------
           | IPO |   | View3d |   | Buts |  | etc |
           -------   ---------    -------   ------

           ----------------------------------------
           |   Window Manager  Framework          |
           |   (includes interface.c)             |
           ----------------------------------------

---------------------------------------------------------
  (Data level)

        ---------    ---------    ----------   ------
        | Loader |   | Render |   | Blenlib |  | etc |
        ---------    ---------    ----------   ------

           ----------------------------------------
           |   Kernel/DNA  Framework               |
           ----------------------------------------

---------------------------------------------------------
   (internal Library level)

----------------------------------------------------------
   (external library and OS/Posix level)

----------------------------------------------------------

3. Code organisation

Each Module, FrameWork or Library becomes a directory, and gets  
internally a structure like this:

Module/
	intern/        (all internal .c and .h files)
     MOD_module.h   (the external API)
     module_ext.h   (all dependencies to other modules)
     module.h       (all internal dependencies, and to Libraries)

In its simplest form, a C file in a Module then only needs three  
includes:

#include "module.h"  (has <math.h> etc too)
#include "module_ext.h"
#include "MOD_module.h"

By examining these three .h includes, someone can quickly grasp what  
goes on, and what the dependencies are.

BTW: I am not a fan of making one .h file for each .c file. This not  
only takes a load of time to compile, but also adds a lot of work. Of  
course, if needed, you can create as much .h files in 'intern/' as you  
like.

4. Makefiles

Changing one 'BlenderKernel.h" (for example) which has the full  
framework in it, will cause a recompilation of the entire UI... this  
might *seem* bad, but I can confirm that the C compiler will work a  
load lot efficient with fewer and larger includes.
Until 2.0, there was a "blender.h" include, with the full DNA in it.  
Recompiling of all related C files took 1 minute, at a 100 Mhz irix  
machine.
Currently, compiling just two or three c files at 500 Mhz G4 takes a  
minute...

Part of this work should be to remove the engine too (after a debate on  
this of course). Also stuff like streamglue, decrypt, deflate, inflate,  
encrypt should be deminished or completely removed.

There has been code added after 2.0 came out, but it doen't justify  
such incredible slow compilation. With current CPU speeds, this should  
go back to a few seconds again.


-Ton-



------------------------------------------------------------------------ 
--
Ton Roosendaal  Blender Foundation ton@blender.org  
http://www.blender.org