1 $Id: GUIDELINES,v 1.1 2000/01/12 20:37:03 bernie Exp $
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 ;-)
12 The OpenBoopsi tree is structured in this way:
44 These are things you should know:
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.
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.
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.
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
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.
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).
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
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.
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.
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
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
117 3) To include the required headers in your programs or classes just follow
120 #include "common/BoopsiStubs.h"
121 #include "images/VectorGlyph.h"
122 #include "gadgets/ListView.h"
123 #include "RequesterClass.h"
124 #include "MyPrivateInclude.h"
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