Pileus Git - ~andy/gtk/blob - docs/generation.txt

   1 Overview:
   2 ========
   3
   4 This file describes the way that autogeneration
   5 works within the GTK+ source code.
   6
   7 The following files in the gdk/ subdirectory
   8 are autogenerated:
   9
  10   gdkkeysyms.h
  11   gdkcursors.h
  12
  13 The following files in the gtk/ subdirectory
  14 are autogenerated:
  15
  16  gtk.defs
  17    Description of GTK+ types (and some functions) in a lisp-style
  18    format.
  19  gtktypebuiltins.h
  20    Header file including declarations for internal types
  21  gtktypebuiltins_vars.c
  22    Variables for type values for internal types.
  23  gtktypebuiltins_ids.c
  24    Arrays holding information about each internal type.
  25  gtktypebuiltins_evals.c
  26    Arrays holding mapping between enumeration values
  27    and strings.
  28
  29  gtkmarshal.c
  30  gtkmarshal.h
  31    Autogenerated signal marshallers
  32
  33 GDK
  34 ===
  35
  36 gdkkeysyms.h and gdkcursors.h are generated from
  37 the corresponding header files
  38
  39   X11/cursorfont.h
  40   X11/keysymdef.h
  41
  42 by some simple sed scripts. These are not actually
  43 run automatically because we want all the keysyms
  44 even on systems with a limited set.
  45 So the Gdk rule to generate both files (X-derived-headers)
  46 only needs to be rerun for every new release of the X Window
  47 System.
  48
  49 GTK+ - type definitions
  50 =======================
  51
  52 The type definitions are generated from several sources:
  53
  54  gtk-boxed.defs - definitions for boxed types
  55  GTK+ header files
  56  GDK header files
  57
  58 The makeenums.pl script does a heuristic parse of
  59 the header files and extracts all enumerations declarations.
  60 It also recognizes a number of pseudo-comments in the
  61 header files:
  62
  63 Two of these apply to individual enumeration values:
  64
  65   /*< skip >*/
  66
  67  This enumeration value should be skipped.
  68
  69   /*< nick=NICK >*/
  70
  71  The nickname for this value should NICK instead of the
  72  normally guessed value. For instance:
  73
  74   typedef enum {
  75     GTK_TARGET_SAME_APP = 1 << 0,    /*< nick=same-app >*/
  76     GTK_TARGET_SAME_WIDGET = 1 << 1  /*< nick=same-widget >*/
  77   } GtkTargetFlags;
  78
  79  makes the nicks "same-app" and "same-widget", instead of
  80  "app" and "widget" that would normally be used.
  81
  82 The other two apply to entire enumeration declarations.
  83
  84   /*< prefix=PREFIX >*/
  85
  86   Specifies the prefix to be removed from the enumeration
  87   values to generate nicknames.
  88
  89   /*< flags >*/
  90
  91  Specifies that this enumeration is used as a bitfield.
  92  (makenums.pl normally guesses this from the presence of values
  93   with << operators). For instance:
  94
  95   typedef enum                    /*< flags >*/
  96   {
  97     GDK_IM_PREEDIT_AREA      = 0x0001,
  98     GDK_IM_PREEDIT_CALLBACKS = 0x0002,
  99     [ ... ]
 100  } GdkIMStyle;
 101
 102 makeenums.pl can be run into two modes:
 103
 104  1) Generate the gtktypebuiltins_eval.c file (this
 105     contains arrays holding the mapping of
 106     string <=> enumeration value)
 107
 108  2) Generate the enumeration portion of gtk.defs.
 109
 110 The enumearation portion is added to the boxed type
 111 declarations in gtk-boxed.defs to create gtk.defs.
 112
 113 The makeetypes.awk program takes the gtk.defs file, and
 114 from that generates various files depending on the
 115 third parameter passed to it:
 116
 117  macros: gtktypebuiltins.h
 118  variables: gtktypebuiltins_vars.c
 119  entries: gtktypebuiltins_ids.c
 120
 121 GTK+ - marshallers
 122 ==================
 123
 124 The files gtkmarshal.c and gtkmarshal.h include declarations
 125 and definitions for the marshallers needed inside of
 126 GTK+. The marshallers to be generated are listed in
 127 the file gtkmashal.list, which is processed
 128 by genmarshal.pl.
 129
 130 The format of this file is a list of lines:
 131
 132   <retval-type>:<arg1-type>,<arg2-type>,<arg3-type>
 133
 134 e.g.:
 135
 136   BOOL:POINTER,STRING,STRING,POINTER
 137
 138 A marshaller is generated for each line in the file.
 139 The possible types are:
 140
 141  NONE
 142  BOOL
 143  CHAR
 144  INT
 145  UINT
 146  LONG
 147  ULONG
 148  FLOAT
 149  DOUBLE
 150  STRING
 151  ENUM
 152  FLAGS
 153  BOXED
 154  POINTER
 155  OBJECT
 156  FOREIGN    (gpointer data, GtkDestroyNotify notify)
 157  C_CALLBACK (GtkFunction func, gpointer func_data)
 158  SIGNAL     (GtkSignalFunc f, gpointer data)
 159  ARGS       (gint n_args, GtkArg *args)
 160  CALLBACK   (GtkCallBackMarshal marshall,
 161              gpointer data,
 162              GtkDestroyNotify Notify)
 163
 164 Some of these types map to multiple return values - these
 165 are marked above with the return types in parantheses.
 166
 167 NOTES
 168 =====
 169
 170 When autogenerating GTK+ files, the autogenerated
 171 files are often rebuild resulting in the same result.
 172
 173 To prevent unecessary rebuilds of the entire directory, some files
 174 that multiple other source files depend on are not actually written
 175 to directly.  Instead, an intermediate file is written, which
 176 is then compared to the old file, and only if it is different
 177 is it copied into the final location.