[Adonthell-devel] 0.4 cleanup [IMPORTANT]

[Alexandre Courbot]

Hey guys!

Here is a list of the important 0.4 changes I've made. They should ease
the developer life and make things easier to maintain, as the modules
subdivision now appears in the source tree structure (well, at least, it
*starts* appearing). I realized how *much* source code we have today! :)

Once I have your agreement I'll probably write some extra programming
rules down:

- src/Makefile.am now contains a variable indicating the subdirectories
of the different modules (to avoid duplication when building tools or
not).

- The SWIG_MINVER variable set in configure.in allows to control which
minimal version of SWIG is required over a single variable. It is also
used to display the correct error messages in the Makefile.ams. Whenever
we need a newer SWIG, just increase it, and voila.

- The Makefile.ams have slightly been changed so compilation is possible
in another directory than the source directory. For example, if I
untarred adonthell into News/adonthell-0.4 and create a
News/adonthell-0.4-compile directory, and go into the latter, I can
type:

$ ../adonthell-0.4/configure
$ make

And this will build Adonthell in this directory, keeping the source
directory clean. I learned this autoconf trick while working on GCC -
and it's extremly handy when you need to compile/cross-compile for
several architectures (Linux/i386, Windows, Linux/Arm, Linux/PPC, etc.).
It has been backported to 0.3 too (very handy if I make new Windows
binaries)

- I've created directories and moved sources into for the gfx, input,
audio, map and python modules. I haven't touched base because it needs a
cleanup before. I've fixed atk so it compiles with GCC 3.1 and the new
source organisation, but I let Joel move it into it's own directory, as
there is some heavy renaming that will have to be done.

As a rule, every .cc file should start with "using namespace
my_namespace;" where my_namespace is the namespace it belongs. That way
the code won't be bloated with namespace resolution operators, and I
don't think it can lead to confusion. Every .cc file in gfx/ should then
start with "using namespace gfx;" for instance.

The best IMO would be if we limit, as far as possible, the "using"
directive to the namespace the file implements. That is, no "using std"
and suchs. As far as possible, once again - but in the code I've changed
so far, it was just fine.

What would be STRICTLY forbidden however, is to use "using" in .h files.
This is very, very bad design and we did it only because our SWIG
version required it. I hope the latest will be able to handle this
without problems.

Things I'm a little bit worried about (but that's not very serious - at
least the code already so much clearer):

- For every library I'm obliged to include the python cflags everywhere,
just because the wrapper file requires them. Other files doesn't need
them, but I can't write a build target only for the wrapper files. This
make me think that maybe we should separate the Python wrappers from the
libraries.

- If you type, say, "make alextest" in src/ while the needed libraries
aren't build, all you will get is an error at link time, because the
src/ 's Makefile.am doesn't know how to build the sub-libraries. Not
very serious, but maybe there is an elegant way to workaround this?

- The Makefile rules for creating the wrapper files are now duplicated
in each subdirectory. This is bad design, as they are always the same.
Does anyone know a way to have them declared at only one point?

- Of course, as we now use namespace, SWIG 1.3.11 is broken. I've
disabled it for now where it hurts (not used anyway, excepted in
pytest), until I download & test the latest release which is supposed to
support them.

So what works: alextest, joltest (even if I've broken it a little bit)
and schedtest.

What doesn't: pytest (disabled because all the wrapper files can't be
built)

Eventually, the src/ directory should *only* contain the modules
subdirectories and the main program file.

Yet, it still contains the base/rpg (that we need to separate) stuff,
and atk.

Each subdirectory corresponds to a C++ namespace, which Python
representation would be a Python module having the same name.

For instance, in C++ you'd do:
#include "gfx/image.h"

gfx::image myimage;

And in Python:

import adonthell.gfx

myimage = adonthell.gfx.image

I think it would be safer to put all our Python modules in a "adonthell"
module, to isolate our own modules from system/3rd party modules that
might have the same name (as map, gfx are quite standard names). And
doing a "from adonthell import *" wouldn't hurt anybody anyway.

Another thing I thought about (but that should rather be in the post-0.4
plans), is that maybe we could distribute our modules as shared
libraries. This would allow two things:
- More 3rd party control over our word, as someone could well link
dynamically to our libs,
- Distributing the tools (like dlgedit) in packages separated from the
main source tree, which would be much much cleaner.

In this case, separating the Python wrappers from our libraries would
make sense. Well, don't worry too much about it for now, it's just a
random idea - let's think about us before thinking about letting others
easily use our code! ;)

Now our Doxygen graphs will probably look much more l33t! ;) (Gee. Will
run it and document the namespace this evening, probably! ^_^)

Please scold me for all the stuff I've surely broken without even having
noticed! ;)
Alex.
-- 
http://www.gnurou.org