diff --git a/CHANGES.current b/CHANGES.current index 3968e56ee..a4745716e 100644 --- a/CHANGES.current +++ b/CHANGES.current @@ -1,6 +1,17 @@ Version 1.3.25 (In progress) ============================ +04/05/2005: wuzzeb (John Lenz) + [Chicken] + + Added Examples/chicken/egg, an example on how to build a chicken + extension library in the form of an egg. Also updated the + documentation on the different linking options. + + + chicken test-suite now has support to check SWIG with the -proxy + argument if there exists a _proxy_runme.ss file. + + + More fixes for overloaded functions and -proxy + 03/31/2005: wsfulton Turned on extra template features for all languages which were previously only available to Python. diff --git a/Doc/Manual/Chicken.html b/Doc/Manual/Chicken.html index bf132b987..0ef9bc34d 100644 --- a/Doc/Manual/Chicken.html +++ b/Doc/Manual/Chicken.html @@ -104,11 +104,14 @@ generation improvements, part of the wrapper is direct CHICKEN function calls (example_wrap.c) and part is CHICKEN Scheme (example.scm). The basic Scheme code must - be compiled to C using your system's CHICKEN compiler. + be compiled to C using your system's CHICKEN compiler or + both files can be compiled directly using the much simpler csc.

- 
% chicken example.scm -output-file oexample.c
+
+% chicken example.scm -output-file oexample.c
+

@@ -132,7 +135,8 @@

This will generate example_wrap.cxx and example.scm. The basic Scheme code must be - compiled to C using your system's CHICKEN compiler. + compiled to C using your system's CHICKEN compiler or + both files can be compiled directly using the much simpler csc.

@@ -317,21 +321,7 @@

-

17.4 Compilation

- - -

- 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` 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. -

- -

17.5 Linkage

+

17.4 Linkage

@@ -342,51 +332,139 @@ -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. + loadable module. You might also want to use the much simpler + csc or csc.bat.

-

17.5.1 Shared library

+

Each scheme file that is generated + by SWIG contains (declare (uses modname)). This means that to load the + module from scheme code, the code must include (declare (uses modname)). +

-

- The easiest way to use SWIG and CHICKEN is to use the csc compiler - wrapper provided by CHICKEN. Assume you have a SWIG interface file - in example.i and the C functions being wrapped are in example_impl.c. -

+

17.4.1 Static binary or shared library linked at compile time

+ + +

We can easily use csc to build a static binary.

 $ swig -chicken example.i
-$ csc -svk example.scm example_impl.c example_wrap.c
-$ csi example.so test_script.scm
-
-
- -

- You must be careful not to name the example_impl.c file example.c because - when compiling example.scm, csc compiles that into example.c! -

- -

- The test_script.scm should have (load-library 'example "example.so") - and (declare (uses example)). As well, the path to example.so should - be accessable to the loader. You might need to set LD_LIBRARY_PATH. -

- -

17.5.2 Static binary

- - -

Again, we can easily use csc to build a binary.

- -
-
-$ swig -chicken example.i
-$ csc -vk example.scm example_impl.c example_wrap.c test_script.scm -o example
+$ csc -v example.scm example_impl.c example_wrap.c test_script.scm -o example
 $ ./example
-

17.6 Typemaps

+

Similar to the above, any number of module.scm files could be compiled +into a shared library, and then that shared library linked when compiling the +main application.

+ +
+
+$ swig -chicken example.i
+$ csc -sv example.scm example_wrap.c example_impl.c -o example.so
+
+
+ +

The exmaple.so file can then linked with test_script.scm when it +is compiled, in which case test_script.scm must have (declare (uses example)). +Multiple SWIG modules could have been linked into example.so and each +one accessed with a (declare (uses ... )). +

+ +
+
+$ csc -v test_script.scm -lexample
+
+
+ +

An alternative is the test_script.scm can have the code (load-library 'example "example.so"), +in which case the test script does not need to be linked with example.so. The test_script.scm file can then +be run with csi. +

+ +

17.4.2 Building chicken extension libraries

+ + +

Building a shared library like in the above section only works if the library +is linked at compile time with a script containing (declare (uses ...)) or is +loaded explictetly with (load-library 'example "example.so"). It is +not the format that chicken expects for extension libraries and eggs. The problem is the +(declare (unit modname)) inside the modname.scm file. There are +two possible solutions to this.

+ +

First, SWIG accepts a -nounit argument, in which case the (declare (unit modname)) +is not generated. Then, the modname.scm and modname_wrap.c files must be compiled into +their own shared library.

+ +
+
+$ csc -sv modname.scm modname_wrap.c modname_impl.c -o modname.so
+
+
+ +

This library can then be loaded by scheme code with the (require 'modname) function. +See +Loading-extension-libraries in the eval unit inside the Chicken manual for more information.

+ +

Another alternative is to run SWIG normally and create a scheme file that contains (declare (uses modname)) +and then compile that file into the shared library as well. For example, inside the mod_load.scm file,

+ +
+
+(declare (uses mod1))
+(declare (uses mod2))
+
+
+ +

Which would then be compiled with

+ +
+
+$ swig -chicken mod1.i
+$ swig -chicken mod2.i
+$ csc -sv mod_load.scm mod1.scm mod2.scm mod1_wrap.c mod2_wrap.c mod1_impl.c mod2_impl.c -o mod.so
+
+
+ +

Then the extension library can be loaded with (require 'mod). As we can see here, +mod_load.scm contains the code that gets exectued when the module is loaded. All this code +does is load both mod1 and mod2. As we can see, this technique is more useful when you want to +combine a few SWIG modules into one chicken extension library, especially if modules are related by +%import

+ +

In either method, the files that are compiled into the shared library could also be +packaged into an egg. The mod1_wrap.c and mod2_wrap.c files that are created by SWIG +are stand alone and do not need SWIG to be installed to be compiled. Thus the egg could be +distributed and used by anyone, even if SWIG is not installed.

+ +

See the Examples/chicken/egg directory in the SWIG source for an example that builds +two eggs, one using the first method and one using the second method.

+ +

17.4.3 Linking multiple SWIG modules with TinyCLOS

+ +

Linking together multiple modules that share type information using the %import +directive while also using -proxy is more complicated. For example, if mod2.i imports mod1.i, then the +mod2.scm file contains references to symbols declared in mod1.scm, +and thus a (declare (uses mod1)) or (require 'mod1) must be exported +to the top of mod2.scm. By default, when SWIG encounters an %import "modname.i" directive, +it exports (declare (uses modname)) into the scm file. This works fine unless mod1 was compiled with +the -nounit argument or was compiled into an extension library with other modules under a different name.

+ +

One option is to override the automatic generation of (declare (uses mod1)) +by passing the -noclosuses option to SWIG when compiling mod2.i. +SWIG then provides the %insert(closprefix) %{ %} directive. Any scheme code inside that directive is inserted into the +generated .scm file, and if mod1 was compiled with -nounit, the directive should contain (require 'mod1). +This option allows for mixed loading as well, where some modules are imported with (declare (uses modname)) +(which means they were compiled without -nounit) and some are imported with (require 'modname).

+ +

The other option is to use the second idea in the above section. Compile all the modules normally, without any +%insert(closprefix), -nounit, or -noclosuses. Then the modules will import each other correctly +with (declare (uses ...)). +To create an extension library or an egg, just create a module_load.scm file that (declare (uses ...)) +all the modules.

+ +

17.5 Typemaps

@@ -395,7 +473,7 @@ $ ./example Lib/chicken/chicken.swg.

-

17.7 Pointers

+

17.6 Pointers

@@ -428,7 +506,7 @@ $ ./example type. flags is either zero or SWIG_POINTER_DISOWN (see below).

-

17.7.1 Garbage collection

+

17.6.1 Garbage collection

If the owner flag passed to SWIG_NewPointerObj is 1, NewPointerObj will add a @@ -459,7 +537,7 @@ $ ./example must be called manually.

-

17.8 Unsupported features and known problems

+

17.7 Unsupported features and known problems