cde/programs/dtappbuilder/src/README.src

   1 %W% %G%
   2
   3 $XConsortium: README.src /main/3 1995/11/06 17:09:47 rswiston $
   4
   5 CDE1.0 Application Builder Source Code Documentation
   6 -----------------------------------------------------------------------
   7 -----------------------------------------------------------------------
   8
   9
  10 This document describes the structure & style guidelines for the source
  11 code of the CDE1.0 Application Builder reference implementation.  This
  12 document covers:
  13
  14   I. Source Architecture (libraries & dependencies)
  15  II. Source Directory Structure
  16 III. Style Guidelines
  17         A. Files (.h & .c)
  18             i. naming
  19            ii. structure
  20         B. Functions
  21             i. naming
  22            ii. return values
  23         C. Data
  24             i. naming
  25
  26
  27
  28 I. Source Architecture
  29 ----------------------
  30
  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
  36           Language) files.
  37
  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.
  41
  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.
  45
  46
  47                         libAButil
  48                             |
  49            ----------------------------------
  50            |    |               |           |
  51            |    |            libABobj       |
  52            |    |               |           |
  53            |    |       ------------------  |
  54            |    |       |     |          |  |
  55            |   libABobjXm     |         libABil
  56            |        |         |            |
  57            |        |         |            |
  58            -----------------------------------
  59                 |                     |
  60             Front-end            Code-generator
  61                 ab . . . . . . . . . abmf
  62
  63
  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
  68                 independent.
  69
  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").
  74
  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).
  80
  81 4. libABil   -  Provides the mechanism for translating the libABobj
  82                 data structures in memory to disk (reads/writes
  83                 BIL, UIL files).
  84
  85
  86
  87
  88 II. Source Directory Structure
  89 -------------------------------
  90
  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:
  94
  95                         /src
  96                           |
  97  -------------------------------------------------------------
  98  |     |     |      |        |          |          |         |
  99 /ab  /abmf /doc  /include  /libABil /libABobj /libABobjXm  /libAButil
 100                     |
 101                 ------------
 102                 |          |
 103                 ab/   ab_private/
 104
 105
 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!).
 110
 111 Below is a desription of each directory & the modules it includes:
 112
 113 ab:
 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
 125
 126 abmf:
 127         abmf -  implements the code generator
 128
 129 libABil:
 130         abil -  implements generic interchange-language functions
 131         bil  -  implements reading/writing BIL files
 132         uil  -  implements reading/writing UIL files
 133
 134 libABobj:
 135         obj  -  implements the AB object data structures
 136         trav -  implements the traversal mechanisms for the 'obj'
 137                 data structures
 138
 139 libABobjXm:
 140         objxm -  implements Motif-izing 'obj' data structures
 141
 142 libAButil:
 143         abio -  implements AB input/output routines
 144         util  - implements general-purpose AB utilities
 145         istr -  implements the AB string library
 146
 147
 148
 149
 150 III. Style Guidelines
 151 ---------------------
 152
 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
 156 readable.
 157
 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).
 161
 162 A. Files
 163    Each module consists of a single public header file, and one or
 164    more private header & source files, as required.
 165
 166    If the module contains a GUI (built with AB), then the module may
 167    also include BIL & AB-generated-source files.
 168
 169    i. naming
 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".
 173
 174             e.g.  brws module -->>
 175
 176                   public header:    brws.h
 177                   private headers:  brws_mthdsP.h
 178                   source files:     brws.c, brws_mthds.c, ...
 179
 180                   bil files:        brws.bil
 181                   AB-generated:     brws_ui.c, brws_stubs.c
 182
 183    ii. structure
 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).
 187
 188
 189 B. Functions
 190
 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
 195
 196    i. naming
 197         a) All public functions are prefixed with the module name*
 198         b) All module-private functions are prefixed with the module
 199            name + "P"
 200         c) All private functions do NOT have the module prefix,
 201            but have a unique and relatively meaningful name
 202
 203              e.g.
 204                 public:         objxm_instantiate_obj()
 205                 module-private: objxmP_merge_args()
 206                 private:        destroy_widget_tree()
 207
 208   ii. return values
 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).
 216
 217
 218 C. Data
 219
 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
 225
 226    i. naming
 227         a) All global data is prefixed with the module name, first
 228            letter capitalized
 229         b) All module-global data is prefixed with the module name
 230            + "P"
 231         c) All private data is NOT prefixed, but should have a
 232            unique and relatively meaningful name
 233
 234             e.g.
 235                 global:        Ab_project
 236                 module-global: abP_grid_size
 237                 private:       gbox_gc
 238
 239
 240
 241
 242
 243
 244
 245
 246
 247
 248