GUIDELINES

   1 $Id: GUIDELINES,v 1.1 2000/01/12 20:37:03 bernie Exp $
   2
   3
   4 OpenBoopsi Guidelines
   5 =====================
   6
   7  This is a brief guideline to explain you how the OpenBoopsi root is
   8  organized, how the makefiles system work, etc. so that you can add
   9  your own class without problems and even without writing your own
  10  Makefile! (more or less ;-)
  11
  12  The OpenBoopsi tree is structured in this way:
  13
  14    OpenBoopsi root/
  15       Makefile
  16       config.mk
  17
  18       images/
  19           Makefile
  20           class1/
  21               Makefile
  22               config.mk
  23               Class1.c
  24               Class1Demo.c
  25           class2/
  26               etc.
  27        gadgets/
  28           Makefile
  29           class1/
  30               Makefile
  31               config.mk
  32               etc.
  33        include/
  34           common/
  35               general.mk
  36               BoopsiStubs.h
  37               etc.
  38           images/
  39               Class1.h
  40               etc.
  41         etc.
  42
  43
  44 These are things you should know:
  45
  46 Makefiles
  47 =========
  48
  49 1) There is a global "config.mk" files where are defined all the compiler
  50  specific variables, like command line options, tools, paths, etc. It is
  51  divided in two sections and you usually should need to modify only the
  52  first one. This file is placed in the OpenBoosi root. Run 'make help' for
  53  a listing of the current configuration.
  54
  55 2) There are different local "config.mk" files. They contain classes
  56  specific informations, i.e. class name, class version, etc. They are
  57  placed in every classes' directory and are required, so if you add a
  58  new class to the OpenBoopsi project you must write one of this file.
  59  An empty config.mk file is provided in the docs/ drawer with all the
  60  explanations you will need.
  61
  62 3) The top level Makefile will call all the makefiles in the other
  63  subdirectories to build the complete distribution, as usual. However,
  64  this Makefile also has a special target which sets up your build
  65  environment. Without this preliminar step you won't be able to compile
  66  anything. Read the INSTALL file or just run 'make help-setup' for a
  67  more detailed explanation of this required step.
  68
  69 4) The makefiles present in every classes' directory are simple dummy
  70  makefiles. They just include the local "config.mk" file and the real
  71  Makefile, so you just need to copy it in your class' directory without
  72  any modifications.
  73
  74 5) It is possibleto customize the local makefiles to pass custom "arguments"
  75  to the true Makefile, so if e.g. your class need to link a specific object
  76  you don't need to modify the general Makefile. Read the docs/empty_Makefile
  77  file for a detailed explanation.
  78
  79 6) You can obviously add to the local Makefile your own targets, e.g. for
  80  creating a custom object that need to be linked to the demo program
  81  (and that you will need to pass to the general Makefile via the argument
  82  system described above).
  83
  84 7) The "general.mk" file in the common/ directory is the Makefile used to
  85  compile all the classes. It is included by the various local makefiles.
  86  This method has three great advantages: 1) if the Makefile is changed or
  87  improved it does not need to be copied in every subdirectories and 2)
  88  you don't need to write your own custom Makefile, just the config.mk
  89  3) if you write a better/different Makefile other user can take
  90  advantages of this just by including your Makefile instead of the
  91  standard one.
  92
  93 8) Remember that custom makefiles must support the defined targets or it
  94  will be impossible to build all the distribution calling the top level
  95  Makefile. You can find a list of the required targets and their purposes
  96  in the general.mk file.
  97
  98 9) If you want your own custom Makefile we suggest you to put it in the
  99  common/ directory (so don't call it Makefile, give it a different name)
 100  and then change your class' local Makefile to include your custom true
 101  Makefile instead of the default one. In this way other people can use your
 102  Makefile without the need to copy it to their subdirectories.
 103
 104
 105 Includes
 106 ========
 107
 108 1) All the includes must be placed in the appropriate include/ subdirectories.
 109  You must leave includes in the classes subdirectories only if they e.g. contain
 110  private definitions needed by the class only, i.e. no other programs or classes
 111  can include it.
 112
 113 2) The makefiles already know where they should search for the needed
 114  includes and how to tell the compiler to find them, so you should not
 115  worry about this.
 116
 117 3) To include the required headers in your programs or classes just follow
 118  this example:
 119
 120 #include "common/BoopsiStubs.h"
 121 #include "images/VectorGlyph.h"
 122 #include "gadgets/ListView.h"
 123 #include "RequesterClass.h"
 124 #include "MyPrivateInclude.h"
 125
 126 4) IMPORTANT: in the example above the last two includes look identical,
 127  however the first should be placed in the include/ dir (and not
 128  in one of its subdirectories!) while the latter should go in the class
 129  own directory.