gtk2/docs/generation.txt
Matthias Clasen 07e7719441 Apply a cleanup patch by Kjartan Maraas (#341812)
2006-10-08  Matthias Clasen  <mclasen@redhat.com>

	* Apply a cleanup patch by Kjartan Maraas  (#341812)
2006-10-08 05:07:55 +00:00

178 lines
4.4 KiB
Plaintext

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.