Overview:

========

This file describes the way that autogeneration

works within the GTK+ source code.

The following files in the gdk/ subdirectory

are autogenerated:

  gdkkeysyms.h

  gdkcursors.h 

The following files in the gtk/ subdirectory 

are autogenerated:

 gtk.defs

   Description of GTK+ types (and some functions) in a lisp-style

   format.

 gtktypebuiltins.h

   Header file including declarations for internal types  

 gtktypebuiltins_vars.c

   Variables for type values for internal types.

 gtktypebuiltins_ids.c

   Arrays holding information about each internal type.

 gtktypebuiltins_evals.c

   Arrays holding mapping between enumeration values

   and strings.

 gtkmarshal.c

 gtkmarshal.h

   Autogenerated signal marshallers

GDK

===

gdkkeysyms.h and gdkcursors.h are generated from

the corresponding header files

  X11/cursorfont.h

  X11/keysymdef.h

by some simple sed scripts. These are not actually

run automatically because we want all the keysyms

even on systems with a limited set.

So the Gdk rule to generate both files (X-derived-headers)

only needs to be rerun for every new release of the X Window

System.

GTK+ - type definitions

=======================

The type definitions are generated from several sources:

 gtk-boxed.defs - definitions for boxed types

 GTK+ header files

 GDK header files

The makeenums.pl script does a heuristic parse of 

the header files and extracts all enumerations declarations.

It also recognizes a number of pseudo-comments in the

header files:

Two of these apply to individual enumeration values:

  /*< skip >*/

 This enumeration value should be skipped.

  /*< nick=NICK >*/

 The nickname for this value should NICK instead of the

 normally guessed value. For instance:

  typedef enum {

    GTK_TARGET_SAME_APP = 1 << 0,    /*< nick=same-app >*/

    GTK_TARGET_SAME_WIDGET = 1 << 1  /*< nick=same-widget >*/

  } GtkTargetFlags;

 makes the nicks "same-app" and "same-widget", instead of

 "app" and "widget" that would normally be used.

The other two apply to entire enumeration declarations.

  /*< prefix=PREFIX >*/

  Specifies the prefix to be removed from the enumeration

  values to generate nicknames.

  /*< flags >*/

 Specifies that this enumeration is used as a bitfield.

 (makenums.pl normally guesses this from the presence of values

  with << operators). For instance:

  typedef enum                    /*< flags >*/

  {

    GDK_IM_PREEDIT_AREA      = 0x0001, 

    GDK_IM_PREEDIT_CALLBACKS = 0x0002, 

    [ ... ]

 } GdkIMStyle;

makeenums.pl can be run into two modes:

 1) Generate the gtktypebuiltins_eval.c file (this

    contains arrays holding the mapping of 

    string <=> enumeration value)

 2) Generate the enumeration portion of gtk.defs.

The enumeration portion is added to the boxed type 

declarations in gtk-boxed.defs to create gtk.defs.

The makeetypes.awk program takes the gtk.defs file, and

from that generates various files depending on the

third parameter passed to it:

 macros: gtktypebuiltins.h

 variables: gtktypebuiltins_vars.c

 entries: gtktypebuiltins_ids.c

GTK+ - marshallers

==================

The files gtkmarshal.c and gtkmarshal.h include declarations

and definitions for the marshallers needed inside of

GTK+. The marshallers to be generated are listed in

the file gtkmashal.list, which is processed

by genmarshal.pl.

The format of this file is a list of lines:

  <retval-type>:<arg1-type>,<arg2-type>,<arg3-type>

e.g.:

  BOOL:POINTER,STRING,STRING,POINTER

A marshaller is generated for each line in the file.

The possible types are:

 NONE

 BOOL

 CHAR

 INT

 UINT

 LONG

 ULONG

 FLOAT

 DOUBLE

 STRING

 ENUM

 FLAGS

 BOXED

 POINTER

 OBJECT

 FOREIGN    (gpointer data, GtkDestroyNotify notify)

 C_CALLBACK (GtkFunction func, gpointer func_data)

 SIGNAL     (GtkSignalFunc f, gpointer data)

 ARGS       (gint n_args, GtkArg *args)

 CALLBACK   (GtkCallBackMarshal marshall,

             gpointer data,

	     GtkDestroyNotify Notify)

Some of these types map to multiple return values - these

are marked above with the return types in parentheses.

NOTES

=====

When autogenerating GTK+ files, the autogenerated

files are often rebuild resulting in the same result.

To prevent unnecessary rebuilds of the entire directory, some files

that multiple other source files depend on are not actually written

to directly.  Instead, an intermediate file is written, which

is then compared to the old file, and only if it is different

is it copied into the final location.