*** empty log message ***
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk/SWIG@820 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
Dave Beazley
parent
501350d86d
commit
24a4a03f3c
1 changed files with 201 additions and 0 deletions
201
NEW
Normal file
201
NEW
Normal file
|
|
@ -0,0 +1,201 @@
|
|||
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.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Loading…
Add table
Add a link
Reference in a new issue