3 $XConsortium: README.src /main/3 1995/11/06 17:09:47 rswiston $
5 CDE1.0 Application Builder Source Code Documentation
6 -----------------------------------------------------------------------
7 -----------------------------------------------------------------------
10 This document describes the structure & style guidelines for the source
11 code of the CDE1.0 Application Builder reference implementation. This
14 I. Source Architecture (libraries & dependencies)
15 II. Source Directory Structure
28 I. Source Architecture
29 ----------------------
31 The Application Builder consists of 2 independent (but tightly
32 integrated) executables:
33 . The AB Front-end (ab): the GUI which is used to 'build'
34 the GUI & application-framework definitions for a CDE
35 application and write them out into BIL (Builder Interchage
38 . The AB Code-generator (abmf): the engine which interprets
39 the BIL files and generates the appropriate Motif/CDE
40 C code/resource files/etc.
42 Both of these executables are based on a common internal mechanism
43 which is implemented in a set of separate libraries. Each library
44 is composed of one or more logical modules.
49 ----------------------------------
53 | | ------------------ |
55 | libABobjXm | libABil
58 -----------------------------------
60 Front-end Code-generator
61 ab . . . . . . . . . abmf
64 1. libAButil - Provides general purpose utility mechanisms used
65 throughout the source code, including definitions of
66 common types and an efficient string-handling
67 mechanism. This library is window-system/toolkit
70 2. libABobj - Provides core mechinism for storing the representation
71 for an application (and the objects it contains) in
72 memory. This library is window-system/toolkit
73 independent ("mechanism", NOT "policy").
75 3. libABobjXm- Provides engine which manipulates the libABobj data
76 structures in a way appropriate for, and dependent on,
77 the Motif toolkit. This library is heavily dependent
78 on the X11 window-system & the Motif toolkit
79 (implements the "policy" for libABobj).
81 4. libABil - Provides the mechanism for translating the libABobj
82 data structures in memory to disk (reads/writes
88 II. Source Directory Structure
89 -------------------------------
91 The source code for the CDE Application Builder is organized
92 in a "flattened" structure corresponding to the architecture
93 described above. The directory structure looks like the following:
97 -------------------------------------------------------------
99 /ab /abmf /doc /include /libABil /libABobj /libABobjXm /libAButil
106 Each directory contains a Makefile, and all header & .c source
107 files for its modules. The "ab" & "ab_private" include directories
108 contain symbolic links to the shared header files in each directory
109 (make include-paths simpler!).
111 Below is a desription of each directory & the modules it includes:
114 pal- implements the mainwindow palette of objects
115 ab - manipulates the UI objects created by the user
116 (create, resize, copy, etc)
117 brws - implements the AB Browser mechanism
118 conn - implements the AB Connections manager
119 proj - implements the AB Project mechanism
120 prop - implements the AB Property Dialogs
121 help - implements the AB Help Editor
122 ttalk- implements the AB ToolTalk Editor
123 abui - implements UI utility routines used by all ab modules
124 abx - implements X utility routines used by all ab modules
127 abmf - implements the code generator
130 abil - implements generic interchange-language functions
131 bil - implements reading/writing BIL files
132 uil - implements reading/writing UIL files
135 obj - implements the AB object data structures
136 trav - implements the traversal mechanisms for the 'obj'
140 objxm - implements Motif-izing 'obj' data structures
143 abio - implements AB input/output routines
144 util - implements general-purpose AB utilities
145 istr - implements the AB string library
150 III. Style Guidelines
151 ---------------------
153 Since the Application Builder is a large & complex application
154 being developed by multiple engineers, a set of coding style
155 conventions have been adopted in order to make the source more easily
158 0. The general C programming style follows the Guidelines
159 outlined in the "The C++ Programming Style Guide Quick Reference"
160 (by HP & SunSoft) (except that indent is 4 spaces, not 8).
163 Each module consists of a single public header file, and one or
164 more private header & source files, as required.
166 If the module contains a GUI (built with AB), then the module may
167 also include BIL & AB-generated-source files.
170 a) All files for a module are prefixed by their module-name.
171 b) The public header file matches identically the module-name.
172 c) Any private header files are appended with a "P".
174 e.g. brws module -->>
176 public header: brws.h
177 private headers: brws_mthdsP.h
178 source files: brws.c, brws_mthds.c, ...
181 AB-generated: brws_ui.c, brws_stubs.c
184 All header & source files generally follow the format contained
185 in the "template.h" & "template.c" files present in each
186 directory (see those files for details).
191 Functions are categorized into 3 basic categories:
192 . public : other modules/libraries may call them
193 . module-private : only files within the module may call them
194 . private : static within a file
197 a) All public functions are prefixed with the module name*
198 b) All module-private functions are prefixed with the module
200 c) All private functions do NOT have the module prefix,
201 but have a unique and relatively meaningful name
204 public: objxm_instantiate_obj()
205 module-private: objxmP_merge_args()
206 private: destroy_widget_tree()
209 a) If a function does not return any specific data and is
210 relatively guaranteed to complete successfully, it is
211 defined as type "void".
212 b) Otherwise, it returns an "int" indicating the degree of
213 success in completing its task, with values >=0 defining
214 success (the return codes defined in libAButil/[ABerror.h]
215 are used for consistency).
220 Data is categorized into 3 classes:
221 . global : other modules within the library/directory can
222 access them (AVOIDED WHENEVER POSSIBLE!)
223 . module-global : different files within a module may access
224 . private : statically defined in a file
227 a) All global data is prefixed with the module name, first
229 b) All module-global data is prefixed with the module name
231 c) All private data is NOT prefixed, but should have a
232 unique and relatively meaningful name
236 module-global: abP_grid_size