[Bf-committers] code restructure

Michel Selten bf-committers@blender.org
Wed, 08 Oct 2003 20:00:13 +0200


On Wed, 2003-10-08 at 15:25, Ton Roosendaal wrote:
> 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

<snip>
No comments on this.

> 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!)

I can think of the following reasons why the 'exception to the rule'
would apply:
- Shared code
  In case module X has a function needed by module Y, that function
  should be moved to the lower Framework layer.
- State changes
  A change in module X that would result in a change that needs to be
  made to module Y. For example, a change in the Material editor module,
  could change the output in the View3d module.
  This is where a good signal/event system would be needed.

> Example: Render, Radiosity, etc.

Hrm, I don't have enough knowledge about that part to see a third
'exception to the rule' with a possible sollution.

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

Well, you know how I think about Spaghetti - great food, but Spaghetti
and code should not go hand in hand. Maybe it's just a little too much
to aim for the best in one attempt. This can be tackled after the
Framework layers are clear, and the restructure has been complete.

> 2. General structure
<snip>

No comments.

> 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)
ok, sounds good.

>      module_ext.h   (all dependencies to other modules)
In my opinion, this file is not needed. This file even slows down the
compilation times. (Not that I mind about a couple of more seconds
compilation time - see below).
I can imagine a couple of .c files that don't need all dependencies
listed in this _ext.h file.

>      module.h       (all internal dependencies, and to Libraries)
See my previous remark.

> 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.

Only the MOD_module.h are the necessary dependencies IMO. This file
should be able to be included as the first include file in a .c file. If
I have a module that depends on MOD_foo.h, I just want to include that
file without having to bother about additional dependencies.

> 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.

Within modules I don't care about the number of .c and .h files either.
Look at the Python module for example.
The 'interface' presented to the outside world however, should be kept
as simple as possible, so 1 include file in this case is perfect! Due to
the size and spaghetti-ness of the Framework module, I would suggest to
have some more MOD_xxx.h files. Again, each of those .h files should be
able to stand on its own. If defined well, then we have the foundation
for less spaghetti code in the future.

Question: Do you plan on restructuring inside the current cvs tree? Or
create a new tree? If the latter is the case, I have something for a
seperate discussion about the usage of tools, but that is besides the
scope of this proposal.

> 4. Makefiles
< snip about efficiency >

To be honest, I don't think we should sacrifice clarity for the reason
of compilation efficiency. I just did a recompile of blender with the
autoconf system on my P4-2.8. This includes the libraries in /intern and
/source/blender. So, no gameblender. Time measured: 3 minutes, 50
seconds. Over 1 minute of that time was spent compiling /intern.
Now, that's still nowhere near the 'few seconds', but that's acceptable
to me. I don't compile blender from scratch often. That's due to the
good dependencies in the build environment.
What I mean to say is that we should revisit the build environment. Get
the dependency generation right, or fix the autoconf system.

My conclusion: This proposal is a lot more 'safer' than my proposal from
a couple of weeks ago. It doesn't introduce the extendability and
flexibility possible with the component architecture, but it sure should
make the source code better to understand.

I will still continue working on my proposal for a component
architecture, even if it's just for learning. Anyway, that's for future
talk...

With regards,
	Michel