$Id: GUIDELINES,v 1.1 2000/01/12 20:37:03 bernie Exp $


OpenBoopsi Guidelines
=====================

 This is a brief guideline to explain you how the OpenBoopsi root is
 organized, how the makefiles system work, etc. so that you can add
 your own class without problems and even without writing your own
 Makefile! (more or less ;-)

 The OpenBoopsi tree is structured in this way:

   OpenBoopsi root/
      Makefile
      config.mk

      images/
          Makefile
          class1/
              Makefile
              config.mk
              Class1.c
              Class1Demo.c
          class2/
              etc.
       gadgets/
          Makefile
          class1/
              Makefile
              config.mk
              etc.
       include/
          common/
              general.mk
              BoopsiStubs.h
              etc.
          images/
              Class1.h
              etc.
        etc.


These are things you should know:

Makefiles
=========

1) There is a global "config.mk" files where are defined all the compiler
 specific variables, like command line options, tools, paths, etc. It is
 divided in two sections and you usually should need to modify only the
 first one. This file is placed in the OpenBoosi root. Run 'make help' for
 a listing of the current configuration.

2) There are different local "config.mk" files. They contain classes
 specific informations, i.e. class name, class version, etc. They are
 placed in every classes' directory and are required, so if you add a
 new class to the OpenBoopsi project you must write one of this file.
 An empty config.mk file is provided in the docs/ drawer with all the
 explanations you will need.

3) The top level Makefile will call all the makefiles in the other
 subdirectories to build the complete distribution, as usual. However,
 this Makefile also has a special target which sets up your build
 environment. Without this preliminar step you won't be able to compile
 anything. Read the INSTALL file or just run 'make help-setup' for a
 more detailed explanation of this required step.

4) The makefiles present in every classes' directory are simple dummy
 makefiles. They just include the local "config.mk" file and the real
 Makefile, so you just need to copy it in your class' directory without
 any modifications.

5) It is possibleto customize the local makefiles to pass custom "arguments"
 to the true Makefile, so if e.g. your class need to link a specific object
 you don't need to modify the general Makefile. Read the docs/empty_Makefile
 file for a detailed explanation.

6) You can obviously add to the local Makefile your own targets, e.g. for
 creating a custom object that need to be linked to the demo program
 (and that you will need to pass to the general Makefile via the argument
 system described above).

7) The "general.mk" file in the common/ directory is the Makefile used to
 compile all the classes. It is included by the various local makefiles.
 This method has three great advantages: 1) if the Makefile is changed or
 improved it does not need to be copied in every subdirectories and 2)
 you don't need to write your own custom Makefile, just the config.mk
 3) if you write a better/different Makefile other user can take
 advantages of this just by including your Makefile instead of the
 standard one.

8) Remember that custom makefiles must support the defined targets or it
 will be impossible to build all the distribution calling the top level
 Makefile. You can find a list of the required targets and their purposes
 in the general.mk file.

9) If you want your own custom Makefile we suggest you to put it in the
 common/ directory (so don't call it Makefile, give it a different name)
 and then change your class' local Makefile to include your custom true
 Makefile instead of the default one. In this way other people can use your
 Makefile without the need to copy it to their subdirectories.


Includes
========

1) All the includes must be placed in the appropriate include/ subdirectories.
 You must leave includes in the classes subdirectories only if they e.g. contain
 private definitions needed by the class only, i.e. no other programs or classes
 can include it.

2) The makefiles already know where they should search for the needed
 includes and how to tell the compiler to find them, so you should not
 worry about this.

3) To include the required headers in your programs or classes just follow
 this example:

#include "common/BoopsiStubs.h"
#include "images/VectorGlyph.h"
#include "gadgets/ListView.h"
#include "RequesterClass.h"
#include "MyPrivateInclude.h"

4) IMPORTANT: in the example above the last two includes look identical,
 however the first should be placed in the include/ dir (and not
 in one of its subdirectories!) while the latter should go in the class
 own directory.