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.