/
index.html
executable file
·2159 lines (2060 loc) · 106 KB
/
index.html
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
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
<head>
<meta charset="utf-8" />
<meta name="generator" content="pandoc" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
<title>index.md</title>
<style>
div#header, header
{
border-bottom: 1px solid #aaa;
margin-bottom: 0.5em;
}
.title
{
text-align: center;
}
.author, .date
{
text-align: center;
}
div#TOC, nav#TOC
{
border-bottom: 1px solid #aaa;
margin-bottom: 0.5em;
}
nav#TOC {
margin-bottom: var(--line-height);
padding-bottom: 0.5rem;
}
nav#TOC input {
display: none;
}
nav#TOC label {
color: var(--color-link);
cursor: pointer;
}
nav#TOC > ul {
display: none;
}
nav#TOC > input:checked + ul {
display: block;
}
@media print
{
div#TOC, nav#TOC
{
display: none;
}
}
div.content
{
color: #111111;
font-size: 14px;
line-height: 1.6;
}
div#cgit a
{
color: #1212a0;
}
div#cgit a.sourceLine
{
color: #111111;
}
h1, h2, h3, h4, h5, h6
{
font-family: "Helvetica Neue", Helvetica, "Liberation Sans", Calibri, Arial, sans-serif;
page-break-after: avoid;
margin: 20px 0 10px;
padding: 0;
}
h2 {
border-bottom: 1px solid #ccc;
}
div div
{
}
section section
{
margin-left: 2em;
}
p {}
blockquote
{
font-style: italic;
}
li
{
}
li > p
{
margin-top: 1em;
}
ul
{
}
ul li
{
}
ol
{
}
ol li
{
}
hr {}
sub
{
}
sup
{
}
em
{
}
em > em
{
font-style: normal;
}
strong
{
}
a
{
text-decoration: none;
}
@media screen
{
a:hover
{
text-decoration: underline;
}
}
@media print
{
a {
color: black;
background: transparent;
}
a[href^="http://"]:after, a[href^="https://"]:after
{
content: " (" attr(href) ") ";
font-size: 90%;
}
}
img
{
vertical-align: middle;
}
div.figure
{
margin-left: auto;
margin-right: auto;
text-align: center;
font-style: italic;
}
p.caption
{
}
pre, code
{
background-color: #f8f8f8;
white-space: pre-wrap;
white-space: -moz-pre-wrap !important;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
word-wrap: break-word;
}
pre
{
padding: 0.5em;
border-radius: 5px;
background-color: #f8f8f8;
border: 1px solid #ccc;
font-size: 13px;
line-height: 19px;
overflow: auto;
padding: 6px 10px;
margin-left: 0.5em;
margin-right: 0.5em;
}
@media screen
{
pre
{
white-space: pre;
overflow: auto;
border: 1px dotted #777;
}
}
code
{
}
p > code, li > code
{
padding-left: 2px;
padding-right: 2px;
}
li > p code
{
padding: 2px;
}
span.math
{
}
div.math
{
}
span.LaTeX
{
}
eq
{
}
table
{
border-collapse: collapse;
border-spacing: 0;
margin-left: auto;
margin-right: auto;
}
thead
{
border-bottom: 1pt solid #000;
background-color: #eee;
}
tr.header
{
}
tbody
{
}
tr {
}
tr.odd:hover, tr.even:hover
{
background-color: #eee;
}
tr.odd {}
tr.even {}
td, th
{
vertical-align: top;
vertical-align: baseline;
padding-left: 0.5em;
padding-right: 0.5em;
padding-top: 0.2em;
padding-bottom: 0.2em;
}
th
{
font-weight: bold;
}
tfoot
{
}
caption
{
caption-side: top;
border: none;
font-size: 0.9em;
font-style: italic;
text-align: center;
margin-bottom: 0.3em;
padding-bottom: 0.2em;
}
dl
{
border-top: 2pt solid black;
padding-top: 0.5em;
border-bottom: 2pt solid black;
}
dt
{
font-weight: bold;
}
dd+dt
{
border-top: 1pt solid black;
padding-top: 0.5em;
}
dd
{
margin-bottom: 0.5em;
}
dd+dd
{
border-top: 1px solid black;
}
a.footnote, a.footnoteRef {
font-size: small;
vertical-align: text-top;
}
a[href^="#fnref"], a.reversefootnote
{
}
@media print
{
a[href^="#fnref"], a.reversefootnote
{
display: none;
}
}
div.footnotes
{
}
div.footnotes li[id^="fn"]
{
}
@media print
{
.noprint
{
display:none;
}
}
</style>
</head>
<body>
<nav id="TOC" role="doc-toc">
<strong>Contents</strong><label for="contents">⊕</label>
<input type="checkbox" id="contents">
<ul>
<li><a href="#gluegen-manual">GlueGen Manual</a>
<ul>
<li><a href="#references">References</a></li>
<li><a href="#chapter-1---introduction"><span id="Chapter1">Chapter 1
- Introduction</span></a>
<ul>
<li><a
href="#introduction"><span id="SecIntroduction">Introduction</span></a></li>
<li><a
href="#structure-of-the-generated-glue-code"><span id="SecStructure">Structure
of the Generated Glue Code</span></a></li>
<li><a href="#unique-features"><span id="SecUnique">Unique
Features</span></a></li>
<li><a
href="#background-and-design-principles"><span id="SecBackground">Background
and Design Principles</span></a></li>
</ul></li>
<li><a href="#chapter-2---using-gluegen"><span id="Chapter2">Chapter 2
- Using GlueGen</span></a>
<ul>
<li><a
href="#acquiring-and-building-gluegen"><span id="SecAcquiring">Acquiring
and Building GlueGen</span></a></li>
<li><a href="#basic-operation"><span id="SecBasic">Basic
Operation</span></a></li>
<li><a
href="#running-gluegen-as-an-ant-task"><span id="SecAnt">Running
GlueGen as an Ant Task</span></a></li>
<li><a href="#jcpp"><span id="SecJCPP">JCPP</span></a></li>
<li><a href="#stub-headers"><span id="SecStub">Stub
Headers</span></a></li>
<li><a href="#32--and-64-bit-considerations"><span id="Sec32">32- and
64-bit Considerations</span></a></li>
<li><a href="#opaque-directives"><span id="SecOpaque">Opaque
Directives</span></a></li>
<li><a
href="#argument-name-substitution"><span id="SecSubstitution">Argument
Name Substitution</span></a></li>
<li><a
href="#configuration-file-directives"><span id="SecConfiguration">Configuration
File Directives</span></a></li>
</ul></li>
<li><a
href="#chapter-3---configuration-file-examples"><span id="Chapter3">Chapter
3 - Configuration File Examples</span></a>
<ul>
<li><a
href="#simplest-possible-example"><span id="SecSimplest">Simplest
possible example</span></a></li>
<li><a href="#arrays-and-buffers"><span id="SecArrays">Arrays and
buffers</span></a></li>
<li><a href="#string-handling"><span id="SecString">String
handling</span></a></li>
<li><a href="#memory-allocation"><span id="SecMemory">Memory
allocation</span></a></li>
<li><a
href="#ingoing-and-outgoing-structs"><span id="SecStructs">Ingoing and
outgoing structs</span></a></li>
<li><a
href="#returned-arrays-of-structs"><span id="SecStructArrays">Returned
arrays of structs</span></a></li>
<li><a
href="#returned-arrays-of-pointers"><span id="SecPointerArrays">Returned
arrays of pointers</span></a></li>
</ul></li>
</ul></li>
</ul>
</nav>
<!---
We convert markdown using pandoc using `gfm` (GitHub-Flavored Markdown) as source format
and `html5+smart` with a custom template as the target.
Recipe:
```
~/pandoc-buttondown-cgit/pandoc_md2html_local.sh index.md > index.html
```
Git repos:
- https://jausoft.com/cgit/users/sgothel/pandoc-buttondown-cgit.git/about/
- https://github.com/sgothel/pandoc-buttondown-cgit
-->
<style>
table, th, td {
border: 1px solid black;
}
</style>
<h1 id="gluegen-manual">GlueGen Manual</h1>
<p><em>Disclaimer: This documented shall be synchronized with source
code, especially the configuration options.</em></p>
<p>Please also consider reading <a
href="../GlueGen_Mapping.html">GlueGen Native Data & Function
Mapping</a> for details on native data and function mappings.</p>
<h2 id="references">References</h2>
<ul>
<li><a href="https://jogamp.org/cgit/gluegen.git/about/">GlueGen Git
Repo</a></li>
<li><a
href="https://jogamp.org/deployment/jogamp-next/javadoc/gluegen/javadoc/">GlueGen
Java™ API-Doc</a></li>
<li><a href="../GlueGen_Mapping.html">GlueGen Native Data & Function
Mapping for Java™</a></li>
<li><a href="https://jogamp.org/gluegen/www/">GlueGen Project
Page</a></li>
<li><a href="../HowToBuild.html">How To Build</a></li>
</ul>
<h2 id="chapter-1---introduction"><span id="Chapter1">Chapter 1 -
Introduction</span></h2>
<h3
id="introduction"><span id="SecIntroduction">Introduction</span></h3>
<p>GlueGen is a tool which automatically generates the Java and JNI code
necessary to call C libraries. It reads as input ANSI C header files and
separate configuration files which provide control over many aspects of
the glue code generation. GlueGen uses a complete ANSI C parser and an
internal representation (IR) capable of representing all C types to
represent the APIs for which it generates interfaces. It has the ability
to perform significant transformations on the IR before glue code
emission. GlueGen is currently powerful enough to bind even low-level
APIs such as the Java Native Interface (JNI) and the AWT Native
Interface (JAWT) back up to the Java programming language.</p>
<p>GlueGen is currently used to generate the JOGL interface to the
OpenGL 3D graphics API and the JOAL interface to the OpenAL audio
library. In the case of JOGL, GlueGen is used not only to bind OpenGL to
Java, but also the low-level windowing system APIs on the Windows, X11
and Mac OS X platforms. The implementation of the JOGL library is
thereby written in the Java programming language rather than in C, which
has offered considerable advantages during the development of the
library.</p>
<p>GlueGen is designed in modular form and can be extended to alter the
glue code emission style or to generate interface code for other
languages than Java.</p>
<p>This manual describes how to use GlueGen to bind new C libraries to
the Java programming language.</p>
<h3
id="structure-of-the-generated-glue-code"><span id="SecStructure">Structure
of the Generated Glue Code</span></h3>
<p>GlueGen supports two basic styles of glue code generation: everything
in one class, or a separate interface and implementing class. The first
mode, "AllStatic", exposes the underlying C functions as a set of static
Java methods in a concrete class. This is a straightforward binding
mechanism, but has the disadvantage of tying users to a concrete class
(which may or may not be a problem) and makes it more difficult to
support certain kinds of call-through-function-pointer semantics
required by certain C APIs. The second mode, "InterfaceAndImpl", exposes
the C functions as methods in an interface and emits the implementation
of that interface into a separate class and package. The implementing
class is not intended to be in the public API; this more strongly
separates the user from the implementation of the API. Additionally,
because it is necessary to hold an instance of the implementing class in
order to access the underlying C routines, it is easier to support
situations where call-through-function-pointer semantics must be
followed, in particular where those function pointers might change from
instance to instance.</p>
<p>The generated glue code follows some basic rules in binding C APIs to
Java:</p>
<ul>
<li>C primitive types are exposed as the corresponding Java primitive
type.</li>
<li>Pointers to typed C primitives (<code>int*</code>,
<code>float*</code>) are bound to java.nio Buffer subclasses
(<code>IntBuffer</code>, <code>FloatBuffer</code>) and optionally to
Java arrays (<code>int[]</code>, <code>float[]</code>).
<ul>
<li>If a C function takes such a pointer as an outgoing argument, two
method overloadings will generally be produced; one which accepts a
Buffer, and one which accepts a primitive array plus an integer offset
argument. The variant taking a Buffer may accept either a "direct" NIO
Buffer or a non-direct one (wrapping a Java array). The exception is
when such a routine is specified by the <a
href="#NioDirectOnly">NioDirectOnly</a> directive to keep a persistent
pointer to the passed storage, in which case only the Buffer variant
will be generated, and will only accept a direct Buffer as
argument.</li>
<li>If a C function returns such a pointer as its result, it will be
exposed as the corresponding Buffer type. In this case it is also
typically necessary to specify to GlueGen via the <a
href="#ReturnValueCapacity">ReturnValueCapacity</a> directive the number
of addressable elements in the resulting array.</li>
</ul></li>
<li>Pointers to <code>void*</code> are bound to java.nio.Buffer.
<ul>
<li>By default any C function accepting a <code>void*</code> argument
will allow either a direct or non-direct java.nio Buffer to be passed as
argument. If the <a href="#NioDirectOnly">NioDirectOnly</a> directive is
specified, however, only a direct Buffer will be accepted.</li>
<li>Similar rules for <code>void*</code> return values apply to those
for pointers to typed primitives.</li>
</ul></li>
<li>To avoid an explosion in the number of generated methods, if a
particular API accepts more than one typed primitive pointer argument,
only two overloadings continue to be produced: one accepting all arrays
as arguments and one accepting all Buffers as arguments. When calling
the variant accepting Buffers, all of the Buffers passed in a particular
call must be either direct or non-direct. Mixing of direct and
non-direct Buffers in a given function call is not supported.</li>
<li>When a java.nio Buffer is passed from Java to C, the position of the
Buffer is taken into account. The resulting pointer passed to C is equal
to the base address of the Buffer plus the position scaled appropriately
for the size of the primitive elements in the Buffer. This feature is
called "auto-slicing", as it mimics the behavior of calling
Buffer.slice() without the overhead of explicit object creation.</li>
<li>Pointers to constant <code>char*</code> may be bound to
java.lang.String using the <a
href="#ArgumentIsString">ArgumentIsString</a> or <a
href="#ReturnsString">ReturnsString</a> directives.</li>
<li><code>#define</code> statements in header files mapping names to
constant values are exposed as public static final constant values in
either the generated interface or AllStatic class.</li>
<li>C structs encountered during the glue code generation process and
referenced by the C functions are exposed as Java classes of the same
name (typically the name to which the struct is typedefed). Each
primitive field in the struct is exposed as two methods; a getter, which
accepts no arguments, and a setter, which accepts as argument a
primitive value of the type of the field. Static factory methods are
exposed allowing allocation of these structs from Java code. The backing
storage for these Java classes is a direct java.nio Buffer. GlueGen
fully supports returning of pointers to C structs up to Java.</li>
</ul>
<h3 id="unique-features"><span id="SecUnique">Unique
Features</span></h3>
<p>GlueGen contains several unique features making it both a powerful
and easy-to-use tool.</p>
<ul>
<li>C structs are exposed as Java classes. The generated code for these
classes supports both 32-bit and 64-bit platforms.</li>
<li>C structs containing function pointers are exposed as Java classes
with methods. This makes it easy to interact with low-level C APIs such
as the AWT Native Interface (JAWT) from the Java programming language
level.
<ul>
<li>In this context, GlueGen automatically detects which argument to the
various function pointers indicates the "this" pointer, hiding it at the
Java level and passing it automatically.</li>
<li>GlueGen offers automatic handling of JNI-specific data types such as
<code>JNIEnv*</code> and <code>jobject</code>. The tool understands that
the <code>JNIEnv*</code> argument is implicit and that
<code>jobject</code> maps to java.lang.Object at the Java programming
language level. While this is most useful when binding JDK-internal APIs
such as the JAWT to Java, there may be other JNI libraries which expose
C functions taking these data types, and GlueGen can very easily bind to
them.</li>
</ul></li>
</ul>
<h3
id="background-and-design-principles"><span id="SecBackground">Background
and Design Principles</span></h3>
<p>This section provides motivation for the design of the GlueGen tool
and is not necessary to understand how to use the tool.</p>
<p>There are many tools available for assisting in the autogeneration of
foreign function interfaces for various high-level languages. Only a few
examples include <a
href="http://alumni.media.mit.edu/~kbrussel/Header2Scheme/">Header2Scheme</a>,
an early tool allowing binding of a limited subset of C++ to the Scheme
programming language; <a href="http://www.swig.org/">SWIG</a>, a tool
released at roughly the same time as Header2Scheme which by now supports
binding C and C++ libraries to a variety of scripting languages; <a
href="http://www.jniwrapper.com/">JNIWrapper</a>, a commercial tool
automating the binding of C APIs to Java; and <a
href="http://web.archive.org/web/20070419183658/http://www.noodleglue.org/noodleglue/noodleglue.html">NoodleGlue</a>,
a recently-released tool automating the binding of C++ APIs to Java.
Other language-specific tools such as Perl's XS, Boost.Python and many
others exist.</p>
<p>GlueGen was designed with a few key principles in mind. The most
fundamental was to support binding of the lowest-level APIs on a given
platform up to the Java programming language. The intended goal, in the
context of the JOGL project, was to allow subsets of the Win32 and X11
APIs to be exposed to Java, and to use those APIs to write the
behind-the-scenes OpenGL context creation and management code in Java
instead of C. This informed several other design goals:</p>
<ul>
<li>Avoid touching the C headers as much as possible. This makes it
easier to upgrade to a more recent version of the C API just by copying
in a new set of headers.</li>
<li>Avoid touching the generated glue code completely.</li>
<li>Avoid having to hand-write a lot of generated glue code. Instead,
handle many complex constructs automatically and provide sufficient
control over the glue code generation to avoid having to handwrite
certain native methods where one or two lines of tweaking would
suffice.</li>
<li>Support all C constructs in the parser and intermediate
representation. The rationale is that it is acceptable to cut corners in
the number of constructs supported in the Java binding, but not whether
the tool can internally represent it in its C type system. This design
goal implies starting with complete a ANSI C parser coupled with a
complete C type system.</li>
<li>As the tool is targetting the Java programming language, build the
tool in the Java programming language.</li>
</ul>
<p>In order to make the problem more tractable, support for binding C++
to the Java programming language was not considered. C++ adds many
constructs over ANSI C which make it much more difficult to reason about
and to find a useful subset to support binding to Java. Additionally, it
seems that there are relatively few C++-specific libraries in general
use which could be usefully bound to Java, although this may be a matter
of opinion.</p>
<p>GlueGen was designed with the Java programming language in mind, but
is not necessarily restricted to generating glue code for the Java
language. The tool is divided into separate parse and code generation
phases, and the internal representation is fairly easy to iterate over.
The core driver of GlueGen may therefore be useful in producing other
tools which autogenerate foreign function interfaces to C libraries for
other languages.</p>
<h2 id="chapter-2---using-gluegen"><span id="Chapter2">Chapter 2 - Using
GlueGen</span></h2>
<h3
id="acquiring-and-building-gluegen"><span id="SecAcquiring">Acquiring
and Building GlueGen</span></h3>
<p>The source code for GlueGen may be obtained by cloning the Git
repository:</p>
<pre><code> $git clone --recursive git://jogamp.org/srv/scm/gluegen.git gluegen</code></pre>
<p>To build GlueGen, cd into the gluegen/make folder and invoke ant.</p>
<pre><code> $ant clean all test</code></pre>
<p>Ant 1.8 or later and a Java 6 compatible JDK is required.</p>
<h4 id="common-build-problems"><span id="SecCommon">Common Build
Problems</span></h4>
<p><strong>CharScanner; panic: ClassNotFoundException:
com.jogamp.gluegen.cgram.CToken</strong><br />
This occurs because ANTLR was dropped into the Extensions directory of
the JRE/JDK. On Windows and Linux, delete any ANTLR jars from
jre/lib/ext, and on Mac OS X, delete them from /Library/Java/Extensions.
Use the antlr.jar property in the build.xml to point to a JRE-external
location of this jar file.</p>
<h3 id="basic-operation"><span id="SecBasic">Basic Operation</span></h3>
<p>GlueGen can be run either as an executable jar file
(<code>java -jar gluegen.jar</code>; note
that antlr.jar must be in the same directory as gluegen.jar in order for
this invocation to work) or from within Ant as described in the
following section. When run from the command line, GlueGen accepts four
kinds of command-line arguments:</p>
<ul>
<li>-I<em>dir</em> (optional) adds <em>dir</em> to the include path.
Similarly to a C compiler or preprocessor, GlueGen scans a set of
directories to locate header files it encounters in
<code>#include</code> directives. Unlike most C preprocessors, however,
GlueGen has no default include path, so it is typically necessary to
supply at least one <code>-I</code> option on the command line in order
to handle any <code>#include</code> directives in the file being
parsed.</li>
<li>-E<em>emitterClassName</em> (optional) uses
<em>emitterClassName</em> as the fully-qualified name of the emitter
class which will be used by GlueGen to generate the glue code. The
emitter class must implement the
<code>com.jogamp.gluegen.GlueEmitter</code> interface. If this option is
not specified, a <code>com.jogamp.gluegen.JavaEmitter</code> will be
used by default.</li>
<li>-C<em>cfgFile</em> adds <em>cfgFile</em> to the list of
configuration files used to set up the chosen emitter. This is the means
by which a large number of options are passed in to the GlueGen tool and
to the emitter in particular. Configuration files are discussed more in
the following section.</li>
<li>[ filename | - ] selects the file or standard input from which
GlueGen should read the C header file for which glue code should be
generated. This must be the last command-line argument, and only one
filename argument is supported. To cause multiple header files to be
parsed, write a small .c file #including the multiple headers and point
GlueGen at the .c file.</li>
</ul>
<h3 id="running-gluegen-as-an-ant-task"><span id="SecAnt">Running
GlueGen as an Ant Task</span></h3>
<p>GlueGen can also be invoked as a subtask within Ant. In order to do
so, a path element should be defined as follows:</p>
<pre><code> <path id="gluegen.classpath">
<pathelement location="${gluegen.jar}" />
<pathelement location="${antlr.jar}" />
</path></code></pre>
<p>where the <code>gluegen.jar</code> and <code>antlr.jar</code>
properties point to the respective jar files. A taskdef defining the
GlueGen task should then be specified as follows:</p>
<pre><code><taskdef name="gluegen"
classname="com.jogamp.gluegen.ant.GlueGenTask"
classpathref="gluegen.classpath" /></code></pre>
<p>At this point GlueGen may be invoked as follows:</p>
<pre><code><gluegen src="[header to parse]"
config="[configuration file]"
includeRefid="[dirset for include path]"
emitter="com.jogamp.gluegen.JavaEmitter">
<classpath refid="gluegen.classpath" />
</gluegen></code></pre>
<p>Please see the <a href="http://jogamp.org/jogl/">JOGL</a> and <a
href="http://jogamp.org/joal/">JOAL</a> build.xml files for concrete,
though non-trivial, examples of how to invoke GlueGen via Ant.</p>
<h3 id="jcpp"><span id="SecJCPP">JCPP</span></h3>
<p>GlueGen contains and uses the <a
href="https://jogamp.org/cgit/jcpp.git/about/">C preprocessor JCPP</a>,
see <a href="https://www.anarres.org/projects/jcpp/">original
homepage</a>.</p>
<p>Constant values intended for use by end users are defined in many C
libraries' headers using <code>#define</code>s rather than constant int
declarations. If the header would be processed by a full C preprocessor,
the <code>#define</code> statement's macro name become unavailable for
processing by the glue code generator. Using JCPP allows us to utilize
the <code>#define</code> macro names and values.</p>
<p>JCPP is largely an invisible part of the glue code generation
process. If GlueGen's output is not as expected and there is heavy use
of the C preprocessor in the header, run JCPP against the header
directly (JCPP takes simply the -I and filename arguments accepted by
GlueGen) and examine the output.</p>
<h3 id="stub-headers"><span id="SecStub">Stub Headers</span></h3>
<p>As much as is possible, GlueGen is intended to operate on unmodified
C header files, so that it is easy to upgrade the given C API being
bound to Java simply by dropping in a new set of header files. However,
most C headers contain references to standard headers like
<code>stdio.h</code>, and if this header is parsed by GlueGen, the tool
will automatically attempt to generate Java entry points for such
routines as <code>fread</code> and <code>fwrite</code>, among others. It
is impractical to exclude these APIs on a case by case basis. Therefore,
the suggested technique to avoid polluting the binding with these APIs
is to "stub out" the headers.</p>
<p>GlueGen searches the include path for headers in the order the
include directories were specified to the tool. Placing another
directory in front of the one in which the bulk of the headers are found
allows, for example, an alternative <code>stdio.h</code> to be inserted
which contains few or no declarations but which satisfies the need of
the dependent header to find such a file.</p>
<p>GlueGen uses a complete ANSI and GNU C parser written by John
Mitchell and Monty Zukowski from the set of grammars available for the
ANTLR tool by Terrence Parr. As a complete C parser, this grammar
requires all data types encountered during the parse to be fully
defined. Often a particular header will be included by another one in
order to pick up data type declarations rather than API declarations.
Stubbing out the header with a smaller one providing a "fake" type
declaration is a useful technique for avoiding the binding of
unnecessary APIs during the glue code process.</p>
<p>Here's an example from the JOGL glue code generation process. The
<code>glext.h</code> header defining OpenGL extensions references
<code>stddef.h</code> in order to pick up the <code>ptrdiff_t</code>
data type. We choose to not include the real stddef.h but instead to
swap in a stub header. The contents of this header are therefore as
follows:</p>
<pre><code> #if defined(_WIN64)
typedef __int64 ptrdiff_t;
#elif defined(__ia64__) || defined(__x86_64__)
typedef long int ptrdiff_t;
#else
typedef int ptrdiff_t;
#endif</code></pre>
<p>This causes the ptrdiff_t data type to be defined appropriately for
the current architecture. It will be referenced during the glue code
generation and cause a Java value of the appropriate type (int or long)
to be used to represent it.</p>
<p>This is not the best example because it involves a data type which
changes size between 32- and 64-bit platforms, and there are otner
considerations to take into account in these situations (see the section
<a href="#Sec32">32- and 64-bit considerations</a>). Here's another
example, again from the JOGL source tree. JOGL binds the AWT Native
Interface, or JAWT, up to the Java programming language so that the
low-level code which binds OpenGL contexts to Windows device contexts
may be written in Java. The JDK's <code>jawt_md.h</code> on the Windows
platform includes <code>windows.h</code> to pick up the definitions of
data types such as <code>HWND</code> (window handle) and
<code>HDC</code> (handle to device context). However, it is undesirable
to try to parse the real <code>windows.h</code> just to pick up these
typedefs; not only does this header contain thousands of unneeded APIs,
but it also uses certain macro constructs not supported by GlueGen's
contained <a href="#SecJCPP">C preprocessor</a>. To avoid these
problems, a "stub" <code>windows.h</code> header is placed in GlueGen's
include path containing only the necessary typedefs:</p>
<pre><code> typedef struct _handle* HANDLE;
typedef HANDLE HDC;
typedef HANDLE HWND;</code></pre>
<p>Note that it is essential that the type being specified to GlueGen is
compatible at least in semantics with the real definition of the HANDLE
typedef in the real <code>windows.h</code>, so that during compilation
of GlueGen's autogenerated C code, when the real <code>windows.h</code>
is referenced by the C compiler, the autogenerated code will compile
correctly.</p>
<p>This example is not really complete as it also requires <a
href="#Sec32">consideration of the size of data types on 32- and 64-bit
platforms</a> as well as a discussion of how certain <a
href="#SecOpaque">opaque data types</a> are described to GlueGen and
exposed in its autogenerated APIs. Nonetheless, it illustrates at a
basic level why using a stub header is necessary and useful in certain
situations.</p>
<h3 id="32--and-64-bit-considerations"><span id="Sec32">32- and 64-bit
Considerations</span></h3>
<p>When binding C functions to the Java programming language, it is
important that the resulting Java code support execution on a 64-bit
platform if the associated native methods are compiled appropriately. In
other words, the public Java API should not change if the underlying C
data types change to another data model such as LP64 (in which longs and
pointers become 64-bit).</p>
<p>GlueGen internally maintains two descriptions of the underlying C
data model: one for 32-bit architectures and one for 64-bit
architectures. These machine descriptions are used when deciding the
mapping between integral C types such as int and long and the
corresponding Java types, as well as when laying out C structs for
access by the Java language. For each autogenerated C struct accessor,
both a 32-bit and 64-bit variant are generated behind the scenes,
ensuring that the resulting Java code will run correctly on both 32-bit
and 64-bit architectures.</p>
<p>When generating the main class containing the bulk of the method
bindings, GlueGen uses the 64-bit machine description to map C data
types to Java data types. This ensures that the resulting code will run
properly on 64-bit platforms. Note that it also generally means that C
<code>long</code>s will be mapped to Java <code>long</code>s, since an
LP64 data model is assumed.</p>
<p>If <a href="#SecOpaque">Opaque directives</a> are used to cause a
given C integer or pointer data type to be mapped directly to a Java
primitive type, care should be taken to make sure that the Java
primitive type is wide enough to hold all of the data even on 64-bit
platforms. Even if the data type is defined in the header file as being
only a 32-bit C integer, if there is a chance that on a 64-bit platform
the same header may define the data type as a 64-bit C integer or long,
the Opaque directive should map the C type to a Java long.</p>
<h3 id="opaque-directives"><span id="SecOpaque">Opaque
Directives</span></h3>
<p>Complex header files may contain declarations for certain data types
that are either too complex for GlueGen to handle or unnecessarily
complex from the standpoint of glue code generation. In these situations
a stub header may be used to declare a suitably compatible typedef for
the data type. An <a href="#Opaque">Opaque</a> directive can be used to
map the resulting typedef to a Java primitive type if it is undesirable
to expose it as a full-blown Java wrapper class.</p>
<p>GlueGen hashes all typedefs internally down to their underlying
primitive type. (This is probably not really correct according to the C
type system, but is correct enough from a glue code generation
standpoint, where if the types are compatible they are considered
equivalent.) This means that if the parser encounters</p>
<pre><code> typedef void* LPVOID;</code></pre>
<p>then an Opaque directive stating</p>
<pre><code> Opaque long LPVOID</code></pre>
<p>will cause all <code>void*</code> or <code>LPVOID</code> arguments in
the API to be mapped to Java longs, which is almost never desirable.
Unfortunately, it is not currently possible to distinguish between the
LPVOID typedef and the underlying <code>void*</code> data type in this
situation.</p>
<p>A similar problem occurs for other data types for which Opaque
directives may be desired. For example, a Windows HANDLE equates to a
typedef to <code>void*</code>, but performing this typedef in a stub
header and then adding the Opaque directive</p>
<pre><code> Opaque long HANDLE</code></pre>
<p>will cause all void* arguments to be exposed as Java longs instead of
Buffers, which is again undesirable. Attempting to work around the
problem by typedef'ing HANDLE to an integral type, as in:</p>
<pre><code> typedef long HANDLE;</code></pre>
<p>may itself have problems, because GlueGen will assume the two
integral types are compatible and not perform any intermediate casts
between HANDLE and jlong in the autogenerated C code. (When casting
between a pointer type and a JNI integral type such as jlong in C code,
GlueGen automatically inserts casts to convert the pointer first to an
"intptr_t" and then to the appropriate JNI type, in order to silence
compiler warnings and/or errors.)</p>
<p>What is desired is to produce a new type name distinct from all
others but still compatible with the pointer semantics of the original
type. Then an Opaque directive can be used to map the new type name to,
for example, a Java long.</p>
<p>To implement this in the context of the HANDLE example, the following
typedef may be inserted into the stub header:</p>
<pre><code> typedef struct _handle* HANDLE;</code></pre>
<p>This uses a pointer to an anonymous struct name to produce a new
pointer type. This is legal ANSI C and is supported by GlueGen's parser
without having seen a declaration for "struct _handle". Subsequently, an
Opaque directive can be used to map the HANDLE data type to a Java
long:</p>
<pre><code> Opaque long HANDLE</code></pre>
<p>Now HANDLEs are exposed to Java as longs as desired. A similar
technique is used to expose XIDs on the X11 platform as Java longs.</p>
<h3 id="argument-name-substitution"><span id="SecSubstitution">Argument
Name Substitution</span></h3>
<p>Certain configuration file directives allow the insertion of Java or
C code at various places in the generated glue code, to both eliminate
the need to hand-edit the generated glue code as well as to minimize the
hand-writing of glue code, which sidesteps the GlueGen process. In some
situations the inserted code may reference incoming arguments to compute
some value or perform some operation. Examples of directives supporting
this substitution include <a
href="#ReturnValueCapacity">ReturnValueCapacity</a> and <a
href="#ReturnedArrayLength">ReturnedArrayLength</a>.</p>
<p>The expressions in these directives may contain Java MessageFormat
expressions like <code>{0}</code> which refer to the incoming argument
names to the function. <code>{0}</code> refers to the first incoming
argument.</p>
<p>Strongly-typed C primitive pointers such as <code>int*</code>, which
ordinarily expand to overloaded Java methods taking e.g.
<code>int[]</code> as well as <code>IntBuffer</code>, present a problem.
The expansion to <code>int[] arr</code> also generates an
<code>int arr_offset</code> argument to be able to pass a pointer into
the middle of the array down to C. To allow the same MessageFormat
expression to be used for both cases, the subsitution that occurs when
such a primitive array is referenced is the string
<code>arr, arr_offset</code>; in other
words, the subtituted string contains a comma. This construct may be
used in the following way: the code being manually inserted may itself