diff --git a/NEW b/NEW new file mode 100644 index 000000000..af1818b6e --- /dev/null +++ b/NEW @@ -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. + + + + + + + + + + + +