1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
|
Gauche-gtk scans gtk header files to extract API information
to generate stub files and some header files, using h2stub.scm
program. Since C header files don't provide all necessary
information, and some C construct is too hard to parse by ad-hoc
parser, the extracted information is not enough to generate
complete APIs. Generally, unrecognized API doesn't show up
in Scheme side.
To compensate it, h2stub.scm reads in manually-prepared 'hints'
files, which fills out the missing parts. Due to the large number
of Gtk2 APIs, hints entries haven't covered all of them yet.
If you don't find Scheme API for some Gtk2 calls, it is likely
that the necessary hint entry hasn't written. (There are some
APIs that intentionally dropped from Scheme, though, mostly
because they are irrelevant for Scheme programs).
The stub generation process is done at Gauche-gtk packaging time,
so as far as you download the release tarball, you don't see
h2stub.scm working. If you check out CVS version, however,
you don't see many *.stub files, and need to run 'make stubs'
to generate them.
This file explains how to write hints file entries to some extent.
Note that I regard the whole h2stub stuff is a temporary solution,
and the current spec is just an ad hoc design rather than a
well thought-out one. It may be changed in incompatible way
in the later versions.
[Hint files]
Currently, there are three hint files.
gtk-lib.hints - hints used to generate gtk*.stub
gdk-lib.hints - hints used to generate gdk*.stub
pango-lib.hints - hints used to generate pango-*.stub
Entries in the hints file also affect the following generated files.
gtk-lib.h - definitions and declarations for generated stubs.
gtk-lib.inits - initialization function.
gtk-lib.types - Set of define-type stub entries, used commonly by
all stub files.
Each hints file consists of hint entries, grouped by the
target header files. The following is an excerpt from
gtk-lib.hints:
;;==================================================================
;; gtkaccelgroup.h
;;
(input-file "gtkaccelgroup.h")
;; gtk_accel_group_connect
(define-cproc-fix gtk-accel-group-connect
(fix-arguments! '(accel_group::<gtk-accel-group>
accel_key::<uint>
accel_mods::<int>
accel_flags::<int>
handler::<procedure>))
(fix-body!
"gtk_accel_group_connect(accel_group, accel_key, accel_mods, accel_flags,
Scm_MakeGClosure(handler));
SCM_RETURN(SCM_UNDEFINED);"))
Here, input-file hint entry declares the following hints entries
are related to the APIs extracted from gtkaccelgroup.h.
The input-file declaration specifies which stub file the
generated code from the following entries should go. It is
effective until tne next input-file declaration is seen.
Other top-level expressions are hint directives, described
below.
[Hint directives]
Hint directives can do the following things:
* Insert new stub entries.
* Correct information gathered by scanning C files that affect
the generated stub entries.
Inserting new stub entries
..........................
The following directives are just inserted to the result stub
file directly.
define-cclass arg ...
define-cproc arg ...
define-enum arg ...
define-constant arg ...
define-type arg ...
They can be used when h2stub failed to see necessary API/type/enum
declarations in the header file at all.
You can also insert raw C code piece by the following directive:
raw-code string ...
string ... are joined with newlines, and inserted to the
resulting stub file.
There's also a convenience directive to generate appropriate
Scheme class code for a C structure.
make-opaque <c-name> <type>
<c-name> is a string of the structure. <type> is either one of
:gobject, :indirect, or :refcounted.
This should be used iff h2stub failed to see the type
declaration of C structure <c-name>.
If <type> is :gobject, a stub code that treats <c-name> as
a GObject is generated. That means the Scheme class inherits
<g-object>, and the generated constructor and finalizer handle
reference counting.
If <type> is :refcounted, a stub code assumes <c-name> is
not a GObject, but maintained by reference counting mechanism,
by functions whose name follows the Gtk naming conventions
(e.g. for GtkFooBar, it has gtk_foo_bar_ref and gtk_foo_bar_unref).
The generated constructor and finalizer handle reference counting,
but the Scheme class doesn't inherit <g-object>.
If <type> is :indirect, a stub code assumes the instance of
<c-name> won't be deallocated while Scheme is running, and
doesn't generate any memory management code. The generated
constructor only boxes the given pointer.
Correcting information
......................
Sometimes h2stub does detect an API/type declaration, but failed to
parse some parts of it, causing generating wrong stub entry or
failed to generate the stub entry. (You can find the latter case
by looking at the generated stub file. The entries that can't be
generated are written out as comments, something like the followig:
;; gtk_widget_new
;; (define-cproc gtk-widget-new (type::(UNKNOWN . GType) first_property_name::<const-gchar*> ...::(UNKNOWN . VARARG)) (return <gtk-widget> gtk_widget_new))
In this case, h2stub doesn't know how to handle GType and vararg
arguments, so it couldn't genereate appropriate stub entry for
gtk-widget-new.
To fix this problem, you have to use one of the following directives.
disable-cproc <name>
disable-cclass <name>
These tell h2stub _not_ to generate the stub entry for <name>,
although h2stub recognizes the declaration of <name> from the
C header files. There are some cases that you don't want to
expose certain C functions/structures to Scheme; some of them
are unnecessary to write Scheme programs, and some of them would
cause inconsistency in Scheme data.
define-cproc-fix <name> <body> ...
This fixes the parsed C procedure declaration. The information
of the parsed C procedure is contained in an instance of
<gtk-function> class. This directive first binds the instance
to a variable 'self', then evaluates <body> .... You can
change the slot values of the instance to fix up whatever broken.
See h2stub.scm for the details of the <gtk-function>. Two macros
are provided to be used in <body> for the convenience:
fix-arguments <arglist>
This changes the argument list of the function.
fix-body <string>
This changes the body of the function.
define-cclas-fix <name> <body> ...
This fixes the parsed C structure declaration. The information of
the structure is contained in an instance of <gtk-struct> class.
This directive first binds a variable 'self' to the instance,
then evaluates <body> .... You can change the slot values of
the instance to fix whatever broken. A few macros are provided
to be used in <body> for the convenience:
ignore-field! <field-name>
Eliminates the <field-name> from the structure <name>.
fix-field! <name> <body> ...
Binds a variable 'field' to an instance of <gtk-var> class
that represents the field information of the structure,
then evaluates <body> .... You can change the slot values
of the instance to fix whatever broken.
add-field! <c-name> <c-type> <initargs> ...
Creates a new <gtk-var> instance for a field, and adds it
to the current structure.
add-mixin! <c-mixin-name> ...
Adds classes specified by <c-mixin-name> to the direct
superclass of the current structure.
|
