Ditch some long dead perl cruft
This commit is contained in:
Matthias Clasen
@ -1,177 +0,0 @@
|
||||
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.
|
||||
Reference in New Issue
Block a user