From bc02779c93d257cdfd627bbcffac7e10fccd7586 Mon Sep 17 00:00:00 2001 From: Jonah Beckford Date: Tue, 11 Mar 2003 19:38:00 +0000 Subject: [PATCH] Documentation for fully-knows problem, and update to what is the minimal version of CHICKEN that can be used with SWIG. git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk/SWIG@4514 626c5289-ae23-0410-ae9c-e8d60b6d4f22 --- Doc/Manual/Chicken.html | 155 +++++++++++++++++++++++++++++++++------- 1 file changed, 129 insertions(+), 26 deletions(-) diff --git a/Doc/Manual/Chicken.html b/Doc/Manual/Chicken.html index c296280a7..8f41f600d 100644 --- a/Doc/Manual/Chicken.html +++ b/Doc/Manual/Chicken.html @@ -50,9 +50,11 @@ When confronted with a large C library, CHICKEN users can use SWIG to generate CHICKEN wrappers for the C library. However, - the real advantage of using SWIG with CHICKEN is its - support for C++; object-oriented code is - difficult to wrap by hand in CHICKEN. + the real advantages of using SWIG with CHICKEN are its + support for C++ -- object-oriented code is + difficult to wrap by hand in CHICKEN -- and its typed + pointer representation, essential for C and C++ + libraries involving structures or classes.

@@ -60,19 +62,21 @@

- CHICKEN support was introduced to SWIG in version 1.3.18. SWIG relies - on a recent addition to CHICKEN -- the C_TAGGED_POINTER -- which - is only present in CVS versions of CHICKEN dated after February - 11, 2003, and in releases of CHICKEN with version number - greater than 0.1082. + CHICKEN support was introduced to SWIG in version 1.3.18. SWIG + relies on some recent additions to CHICKEN, which are only + present in releases of CHICKEN with version number + greater than or equal to 0.1099, or in CVS + versions of CHICKEN dated after March 11, 2003.

CHICKEN can be downloaded from http://www.call-with-current-continuation.org/chicken.html You may want to look at any of the examples in Examples/chicken/ or Examples/GIFPlot/Chicken for the basic steps to run SWIG - CHICKEN. We will generically refer to the wrapper as - the generated files. + CHICKEN. + + We will generically refer to the wrapper as the + generated files.

@@ -242,7 +246,7 @@ Almost all good Scheme books describe how to use metaobjects and generic procedures to implement an object-oriented Scheme - system. Please consult with a Scheme book if you are unfamiliar + system. Please consult a Scheme book if you are unfamiliar with the concept.

@@ -258,10 +262,10 @@

- SWIG CHICKEN will call the destructor for TinyCLOS objects - garbage-collected by CHICKEN. It also allows access to the - underlying low-level Scheme procedures with (de)-marshaling of - any TinyCLOS parameters. It is best to learn the TinyCLOS + SWIG CHICKEN will call the destructor for all TinyCLOS objects + that are garbage-collected by CHICKEN. It also allows access to + the underlying low-level Scheme procedures with (de)-marshaling + of any TinyCLOS parameters. It is best to learn the TinyCLOS system by running the Examples/chicken/class/ example.

@@ -271,10 +275,13 @@

Please refer to CHICKEN - A practical and portable Scheme - system - User's manual for detailed help on how to - compile C code for use in a CHICKEN program. Briefly, to - compile C code, be sure to add `chicken-config -cflags` - to your compiler options. + system - User's manual for detailed help on how to compile + C code for use in a CHICKEN program. Briefly, to compile C + code, be sure to add `chicken-config -cflags` or + `chicken-config -shared -cflags` to your compiler + options. Use the -shared option if you want to create + a dynamically loadable module. You might also want to use the + much simpler csc or csc.bat.

22.5 Linkage

@@ -285,7 +292,10 @@ system - User's manual for detailed help on how to link object files to create a CHICKEN Scheme program. Briefly, to link object files, be sure to add `chicken-config - -libs` `chicken-config -extra-libs` to your linker options. + -extra-libs -libs` or `chicken-config -shared + -extra-libs -libs`to your linker options. Use the + -shared option if you want to create a dynamically + loadable module.

All the following examples assume that the module is named @@ -349,9 +359,10 @@ CHICKEN_HOME=/usr/local/share/chicken

- Two non-standard typemaps are supported: clos_in and - clos_out. They are for converting TinyCLOS to and - from low-level CHICKEN SWIG. Here is a quick example: + Two Chicken-specific typemaps are supported: + clos_in and clos_out. They are for + converting TinyCLOS to and from low-level CHICKEN SWIG. Here is + a quick example: 

@@ -380,9 +391,101 @@ CHICKEN_HOME=/usr/local/share/chicken
to SWIG will have correct TinyCLOS representations based on SIMPLE_CLOS_OBJECT. SWIG "knows" the classes that are exposed in the SWIG interface file; it "fully knows" only - those classes that are not forward declarations. Have a look at - the Examples/chicken/vtk/example.i for more - information. + those classes that are not forward declarations. + +

+ + A real-world example of the "fully knows" problem is found in + the VTK visualization library. All VTK classes are derived from + vtkObject. + +
+ 
+   /* FILE: vtkObject.h */
+   class vtkObject {
+      // ...
+   };
+
+
+ +
+ 
+   /* FILE: vtkWindow.h */
+   #include "vtkObject.h"
+
+   class vtkWindow : public vtkObject {
+      // ...
+   };
+
+
+ +
+ 
+   /* FILE: vtkViewport.h */
+   #include "vtkViewport.h"
+
+   class vtkViewport : public vtkObject {
+      // ...
+   };
+
+
+ +
+ 
+   /* FILE: vtkRenderWindow.h */
+   #include "vtkWindow.h"
+
+   class vtkRenderer;
+   class vtkRenderWindow : public vtkWindow {
+      // ...
+      virtual void AddRenderer (vtkRenderer *rendererArg);
+      // ...
+   };
+
+
+ +
+ 
+   /* FILE: vtkRenderer.h */
+   #include "vtkViewport.h"
+
+   class vtkRenderWindow;
+   class vtkRenderer : public vtkViewport {
+      // ...
+      void SetRenderWindow(vtkRenderWindow *);
+      // ...
+   };
+
+
+ +
+ 
+   /* FILE: vtk.i; SWIG interface file */
+   %typemap(clos_in) vtkObject * = SIMPLE_CLOS_OBJECT *;
+   %typemap(clos_out) vtkObject * = SIMPLE_CLOS_OBJECT *;
+   %include "vtkObject.h"
+   %include "vtkWindow.h"
+   %include "vtkViewport.h"
+   %include "vtkRenderWindow.h"
+   %include "vtkRenderer.h"
+
+
+ + After SWIG processes vtkObject.h (from the + %include "vtkObject.h" line), SWIG will have the complete + definition of the vtkObject class because + vtkObject does not contain any references to any + other classes. As it reads vtkWindow.h and + vtkViewport.h, it will already have the definition of + vtkObject, so it will not need a clos_in + or clos_out typemap for the vtkWindow or + vtkViewport subclasses of vtkObject. + However, by the time SWIG gets to %include + "vtkRenderWindow.h", it will not have the definition for the + vtkRenderer class, even though it is used by + vtkRenderWindow. We therefore must + put in clos_in/clos_out typemaps for + vtkRenderer.