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
|
New Features and Important Changes, v1.3
Author(s) : David Beazley
September 3, 2000
1. Introduction
---------------
This document explains some of the most important changes made since
the release of SWIG1.1. The goal is to provide information for people
who want to upgrade an older SWIG interface to the new version.
Most changes pertain to the internal implementation of SWIG and the
organization of the core, parser, and language modules. As a SWIG
user, almost all of these changes are hidden from view except for a
few important cases where changes to the core have dramatically
altered SWIG's old behavior.
2. Types and typemaps
---------------------
2.1 Variables of the form 'const type *' are no longer wrapped as
constants, but as C global variables. The earlier SWIG behavior
was incorrect due to Dave's misinterpretation of 'const' in the C
language specification.
If you have written an interface that expects to create
constants using 'const type *' you will need to rewrite those
specifications using a new %constant directive like this:
%constant(type *) name = value;
Note: this change does not affect variables like this:
const int a = 4; // Still a constant
Note: SWIG still does not parse declarations of the form
'type *const' or 'const type *const' correctly.
2.2 SWIG generally has better support for pointers, 'const',
arrays, and pointers to functions.
2.3 Typemaps are now applied to a more precisely defined set
of datatypes. For example, consider the following
typemap:
%typemap(in) foo * {
... get a foo ...
}
In SWIG1.1, this typemap would get applied to 'foo *',
'foo &', 'const foo *', 'foo []', 'foo[][]', and so forth.
In SWIG1.3, this typemap *only* gets applied to 'foo *'.
It does *NOT* get mapped to the other variants listed
above.
2.4 Bug fix. SWIG now correctly handles typemaps of the form
%typemap(in) Object {
... get an object ...
}
2.5 The memberout typemap is no longer available and is withdrawn.
The old implementation was essentially useless because of the
way in which code was generated.
2.6 The memberin typemap is now inserted inline in the generated
wrapper code. This provides access to scripting-specific
variables in the wrapper function.
3. Type checking
----------------
SWIG no longer uses the functions SWIG_GetPtr() and SWIG_MakePtr() to
parse datatypes in wrapper code. This is because the type of a
pointer is no longer associated with a string, but with a special
"swig_type_info *" object. If you are not using typemaps, this change
should cause no noticable effects. However, if you have written
typemaps to handle pointers, here are the essential details:
3.1 Type name mangling is different in SWIG1.3. For a type of
"int **", SWIG1.1 used to produce a name of the form
"_int_pp". SWIG1.3 on the other hand, produces a name
of the form "_p_p_int". There are a number of reasons for
changing the format, but I'd rather not go into it here. You'll
just have to learn to live with it :-).
3.2 Types are described by a special "swig_type_info *" object. Everywhere
a string was used before, an object of this type will be used.
The "swig_type_info *" for a given type can always be obtained
using macros involving the mangled typename in 3.1. For example,
the type object of of 'int **' is 'SWIGTYPE_p_p_int'.
3.3 Instead of SWIG_GetPtr, a function of the following form is used:
int SWIG_ConvertPtr(ScriptObj *o, void **ptr, swig_type_info *ty);
Note: the function name may differ in certain implementations (read
the source). For example:
int SWIG_ConvertPtr(ScriptObj *o, void **ptr, SWIGTYPE_p_p_int);
Passing a value of '0' for the type will accept any pointer. This
works kind of like 'void *'.
3.4. To create a pointer object, one uses a function similar to
ScriptObj *SWIG_NewPointer(void *ptr, swig_type_info *ty);
It works in a similar manner:
p = SWIG_NewPointer(ptr, SWIGTYPE_p_p_int);
You will have to read the source to get the exact function name
used.
3.5. If, for whatever reason, you need to obtain the 'swig_type_info *'
outside the context of a wrapper file, you can use the
SWIG_TypeQuery() function. For example:
swig_type_info *ty = SWIG_TypeQuery("int **");
this function returns an appropriate type_info structure or NULL
if no such type is registered.
3.6 SWIG does not generate swig_type_info structures for types that are
not actually used in an interface file. As a result, the type
checking tables for SWIG1.3 tend to be much smaller than for SWIG1.1.
*** Note: The old string-based type checking scheme is not going to
return to SWIG so do not ask for backwards compatibility. The new
scheme is substantially faster, it is less error-prone, it requires no
dynamic memory allocation, it works better with the runtime libraries,
and it is simpler to implement than the old string based approach.
4. Deprecated Features (incomplete list)
----------------------------------------
4.1 Documentation system. The old documentation system has been removed
entirely. I expect it to return someday, but it will have a much
different form (probably influenced by XML).
4.2 The %val and %out directives. These directives used to attach
properties to function parameters such as
void foo(%val int *ptr);
The same effect can now be achieved with typemaps:
void foo(int *INPUT);
4.3 Extensions to the %module and %init directive are no longer
supported. For example:
%module example, foo, bar
This used to perform a special kind of multi-module
initialization for static linking. If you really
need to do this, you will have to manually insert
code into the module initialization function.
4.4 %ifdef, %ifndef, %endif, %if, %elif, %else directives are
withdrawn. SWIG has a real preprocessor.
4.5 %checkout directive removed.
5. Language specific changes
----------------------------
5.1 Python shadow classes are much more efficient and pass the shadow objects
directly to the C wrappers.
5.2 Tcl code generation is substantially improved--especially for C++.
5.3 Tcl module can now link to global variables of any type.
5.4 Perl shadow classes improved and optimized somewhat.
5.5 The Guile module represents pointers as smobs. (They used to be
mangled into strings.) Memory leaks and type conversion bugs have been
fixed. The Guile module system, including dynamic loading, and
exceptions are supported. A typemap-driven procedure-documentation
system has been added (requires Guile 1.4). Procedures-with-setters
can be generated.
6. New Features
---------------
6.1 Java module added (although broken in SWIG1.3a4)
6.2 Ruby module added
6.3 Mzscheme module added.
6.4 Integrated preprocessor. You can now use C macros in SWIG interface files.
|
