diff options
Diffstat (limited to 'NEW')
| -rw-r--r-- | NEW | 267 |
1 files changed, 267 insertions, 0 deletions
@@ -0,0 +1,267 @@ +New Features and Important Changes, v1.3 + +Author(s) : David Beazley + +March 21, 2003 + +1. Introduction +--------------- +This document briefly 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; + +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 &', 'foo []', 'foo[][]', and so forth. + + In SWIG1.3, this typemap *only* gets applied to 'foo *' and + 'const 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. + +2.7 SWIG-1.3.10 features a total rewrite of the typemap system. + Typemaps now use a different variable naming scheme. Typemaps + for arguments look like this: + + %typemap(in) sometype { + $1 = convert value ($input); + } + + The variable $1 replaces $target and the variable $input replaces + $source. + + For output values, typemaps look like this: + + %typemap(out) sometype { + $result = create result ($1); + } + + The variable $1 replaces $source and the variable $result replaces + $target. + + See Doc/Manual/Typemaps.html for a full description of the new + typemap system. + +2.8 Multi-argument typemaps are now supported. This solves a common + problem that occurs with functions like this + + void foo(char *buffer, int len); + + where you would like to make the two arguments operate as a single + object in the target language. + +2.9 Types such as 'const int &', 'const double &', are passed as + values instead of pointers. + +2.10 C++ namespaces are now supported. + +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, int flags); + + 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,0); + + Passing a value of '0' for the type will accept any pointer. This + works kind of like 'void *'. The flags argument is reserved for + future expansion. + +3.4. To create a pointer object, one uses a function similar to + + ScriptObj *SWIG_NewPointer(void *ptr, swig_type_info *ty, int flags); + + It works in a similar manner: + + p = SWIG_NewPointer(ptr, SWIGTYPE_p_p_int, 0); + + You will have to read the source to get the exact function name + used. The flags argument is implementation specific and reserved + for future expansion. + +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 now has a real preprocessor. + +4.5 %checkout directive removed. + +4.6 %except and %new are deprecated. + +4.7 %readonly and %readwrite are deprecated. Use %immutable instead. + +4.8 The %addmethods directive has been renamed to %extend. + +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. + +5.6 The Python module now automatically creates shadow class objects from the + C wrappers. This fixes a bunch of hard problems related to typemaps, + exception handling, and more. + +6. New Features +--------------- + +6.1 Java module added + +6.2 Ruby module added + +6.3 Mzscheme module added. + +6.4 Integrated preprocessor. You can now use C macros in SWIG interface files. + +6.5 PHP module added. + +6.6 %rename directive is greatly enhanced to deal with overloaded functions. + +6.7 Support for simple templates + +6.8 Support for overloaded operators. + +6.9 %feature directive. + +6.10 Ocaml module added. + +6.11 XML module added. + +6.12 CHICKEN module added. + +6.13 C# module added. + + + + + + + + + + + + |