From 46144b1be487c279b352edeae9166b2ab9f32fc3 Mon Sep 17 00:00:00 2001 From: Owen Taylor Date: Tue, 6 Jul 1999 00:36:56 +0000 Subject: [PATCH] Added a file that gives documenation about the autogeneration process for Mon Jul 5 20:36:03 1999 Owen Taylor * docs/generation.txt: Added a file that gives documenation about the autogeneration process for various autogenerated files. --- ChangeLog | 20 +++++ ChangeLog.pre-2-0 | 20 +++++ ChangeLog.pre-2-10 | 20 +++++ ChangeLog.pre-2-2 | 20 +++++ ChangeLog.pre-2-4 | 20 +++++ ChangeLog.pre-2-6 | 20 +++++ ChangeLog.pre-2-8 | 20 +++++ docs/generation.txt | 178 ++++++++++++++++++++++++++++++++++++++++++++ 8 files changed, 318 insertions(+) create mode 100644 docs/generation.txt diff --git a/ChangeLog b/ChangeLog index 31d9327705..37f552176f 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,23 @@ +Mon Jul 5 20:36:03 1999 Owen Taylor + + * docs/generation.txt: Added a file that gives + documenation about the autogeneration process for + various autogenerated files. + +Thu Jul 1 15:01:55 1999 Owen Taylor + + * gtk/gtkwindow.c + - Regularize with the rest of GTK+ by making widget->requisition + not reflect the set_usize() + - Always recompute geometry hints, then check if they + changed before sending them to the X server. The + previous checks for changes would fail in a number + of circumstances. + +Thu Jul 1 11:55:59 1999 Owen Taylor + + * gtk/gtkstyle.c: Include for strcmp(). + Wed Jun 30 19:26:36 1999 Owen Taylor * gtk/gtkdnd.c: diff --git a/ChangeLog.pre-2-0 b/ChangeLog.pre-2-0 index 31d9327705..37f552176f 100644 --- a/ChangeLog.pre-2-0 +++ b/ChangeLog.pre-2-0 @@ -1,3 +1,23 @@ +Mon Jul 5 20:36:03 1999 Owen Taylor + + * docs/generation.txt: Added a file that gives + documenation about the autogeneration process for + various autogenerated files. + +Thu Jul 1 15:01:55 1999 Owen Taylor + + * gtk/gtkwindow.c + - Regularize with the rest of GTK+ by making widget->requisition + not reflect the set_usize() + - Always recompute geometry hints, then check if they + changed before sending them to the X server. The + previous checks for changes would fail in a number + of circumstances. + +Thu Jul 1 11:55:59 1999 Owen Taylor + + * gtk/gtkstyle.c: Include for strcmp(). + Wed Jun 30 19:26:36 1999 Owen Taylor * gtk/gtkdnd.c: diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10 index 31d9327705..37f552176f 100644 --- a/ChangeLog.pre-2-10 +++ b/ChangeLog.pre-2-10 @@ -1,3 +1,23 @@ +Mon Jul 5 20:36:03 1999 Owen Taylor + + * docs/generation.txt: Added a file that gives + documenation about the autogeneration process for + various autogenerated files. + +Thu Jul 1 15:01:55 1999 Owen Taylor + + * gtk/gtkwindow.c + - Regularize with the rest of GTK+ by making widget->requisition + not reflect the set_usize() + - Always recompute geometry hints, then check if they + changed before sending them to the X server. The + previous checks for changes would fail in a number + of circumstances. + +Thu Jul 1 11:55:59 1999 Owen Taylor + + * gtk/gtkstyle.c: Include for strcmp(). + Wed Jun 30 19:26:36 1999 Owen Taylor * gtk/gtkdnd.c: diff --git a/ChangeLog.pre-2-2 b/ChangeLog.pre-2-2 index 31d9327705..37f552176f 100644 --- a/ChangeLog.pre-2-2 +++ b/ChangeLog.pre-2-2 @@ -1,3 +1,23 @@ +Mon Jul 5 20:36:03 1999 Owen Taylor + + * docs/generation.txt: Added a file that gives + documenation about the autogeneration process for + various autogenerated files. + +Thu Jul 1 15:01:55 1999 Owen Taylor + + * gtk/gtkwindow.c + - Regularize with the rest of GTK+ by making widget->requisition + not reflect the set_usize() + - Always recompute geometry hints, then check if they + changed before sending them to the X server. The + previous checks for changes would fail in a number + of circumstances. + +Thu Jul 1 11:55:59 1999 Owen Taylor + + * gtk/gtkstyle.c: Include for strcmp(). + Wed Jun 30 19:26:36 1999 Owen Taylor * gtk/gtkdnd.c: diff --git a/ChangeLog.pre-2-4 b/ChangeLog.pre-2-4 index 31d9327705..37f552176f 100644 --- a/ChangeLog.pre-2-4 +++ b/ChangeLog.pre-2-4 @@ -1,3 +1,23 @@ +Mon Jul 5 20:36:03 1999 Owen Taylor + + * docs/generation.txt: Added a file that gives + documenation about the autogeneration process for + various autogenerated files. + +Thu Jul 1 15:01:55 1999 Owen Taylor + + * gtk/gtkwindow.c + - Regularize with the rest of GTK+ by making widget->requisition + not reflect the set_usize() + - Always recompute geometry hints, then check if they + changed before sending them to the X server. The + previous checks for changes would fail in a number + of circumstances. + +Thu Jul 1 11:55:59 1999 Owen Taylor + + * gtk/gtkstyle.c: Include for strcmp(). + Wed Jun 30 19:26:36 1999 Owen Taylor * gtk/gtkdnd.c: diff --git a/ChangeLog.pre-2-6 b/ChangeLog.pre-2-6 index 31d9327705..37f552176f 100644 --- a/ChangeLog.pre-2-6 +++ b/ChangeLog.pre-2-6 @@ -1,3 +1,23 @@ +Mon Jul 5 20:36:03 1999 Owen Taylor + + * docs/generation.txt: Added a file that gives + documenation about the autogeneration process for + various autogenerated files. + +Thu Jul 1 15:01:55 1999 Owen Taylor + + * gtk/gtkwindow.c + - Regularize with the rest of GTK+ by making widget->requisition + not reflect the set_usize() + - Always recompute geometry hints, then check if they + changed before sending them to the X server. The + previous checks for changes would fail in a number + of circumstances. + +Thu Jul 1 11:55:59 1999 Owen Taylor + + * gtk/gtkstyle.c: Include for strcmp(). + Wed Jun 30 19:26:36 1999 Owen Taylor * gtk/gtkdnd.c: diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8 index 31d9327705..37f552176f 100644 --- a/ChangeLog.pre-2-8 +++ b/ChangeLog.pre-2-8 @@ -1,3 +1,23 @@ +Mon Jul 5 20:36:03 1999 Owen Taylor + + * docs/generation.txt: Added a file that gives + documenation about the autogeneration process for + various autogenerated files. + +Thu Jul 1 15:01:55 1999 Owen Taylor + + * gtk/gtkwindow.c + - Regularize with the rest of GTK+ by making widget->requisition + not reflect the set_usize() + - Always recompute geometry hints, then check if they + changed before sending them to the X server. The + previous checks for changes would fail in a number + of circumstances. + +Thu Jul 1 11:55:59 1999 Owen Taylor + + * gtk/gtkstyle.c: Include for strcmp(). + Wed Jun 30 19:26:36 1999 Owen Taylor * gtk/gtkdnd.c: diff --git a/docs/generation.txt b/docs/generation.txt new file mode 100644 index 0000000000..429f9ff364 --- /dev/null +++ b/docs/generation.txt @@ -0,0 +1,178 @@ +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. +[ yosh - is this correct? ] + +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 enumearation 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: + + :,, + +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 parantheses. + +NOTES +===== + +When autogenerating the GTK header files, the autogenerated +files are often rebuild resulting in the same result. + +To prevent unecessary rebuilds of the entire directory, the +actual files are actually not written to directly. Instead, an +intermediate file is written, this is compared to the +old file, and only if it is different is it copied into +the final location. + + +