diff options
Diffstat (limited to 'Doc/Manual')
| -rw-r--r-- | Doc/Manual/Allegrocl.html | 2150 | ||||
| -rw-r--r-- | Doc/Manual/Chicken.html | 597 | ||||
| -rw-r--r-- | Doc/Manual/Contents.html | 1 | ||||
| -rw-r--r-- | Doc/Manual/Doxygen.html | 2 | ||||
| -rw-r--r-- | Doc/Manual/Extending.html | 8 | ||||
| -rw-r--r-- | Doc/Manual/Go.html | 65 | ||||
| -rw-r--r-- | Doc/Manual/Guile.html | 2 | ||||
| -rw-r--r-- | Doc/Manual/Java.html | 2 | ||||
| -rw-r--r-- | Doc/Manual/Javascript.html | 17 | ||||
| -rw-r--r-- | Doc/Manual/Modula3.html | 942 | ||||
| -rw-r--r-- | Doc/Manual/Perl5.html | 2 | ||||
| -rw-r--r-- | Doc/Manual/Php.html | 183 | ||||
| -rw-r--r-- | Doc/Manual/Pike.html | 246 | ||||
| -rw-r--r-- | Doc/Manual/Preprocessor.html | 2 | ||||
| -rw-r--r-- | Doc/Manual/Python.html | 23 | ||||
| -rw-r--r-- | Doc/Manual/R.html | 4 | ||||
| -rw-r--r-- | Doc/Manual/SWIG.html | 4 | ||||
| -rw-r--r-- | Doc/Manual/SWIGPlus.html | 4 | ||||
| -rw-r--r-- | Doc/Manual/Warnings.html | 2 | ||||
| -rw-r--r-- | Doc/Manual/Windows.html | 60 |
20 files changed, 203 insertions, 4113 deletions
diff --git a/Doc/Manual/Allegrocl.html b/Doc/Manual/Allegrocl.html deleted file mode 100644 index 4069ecd8b..000000000 --- a/Doc/Manual/Allegrocl.html +++ /dev/null @@ -1,2150 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> -<html> -<head> -<title>SWIG and Allegro Common Lisp</title> -<link rel="stylesheet" type="text/css" href="style.css"> -<meta http-equiv="content-type" content="text/html; charset=UTF-8"> -</head> - -<body bgcolor="#ffffff"> - -<H1><a name="Allegrocl">20 SWIG and Allegro Common Lisp</a></H1> -<!-- INDEX --> -<div class="sectiontoc"> -<ul> -<li><a href="#Allegrocl_nn2">Basics</a> -<ul> -<li><a href="#Allegrocl_nn3">Running SWIG</a> -<li><a href="#Allegrocl_nn4">Command Line Options</a> -<li><a href="#Allegrocl_nn5">Inserting user code into generated files</a> -</ul> -<li><a href="#Allegrocl_nn6">Wrapping Overview</a> -<ul> -<li><a href="#Allegrocl_nn7">Function Wrapping</a> -<li><a href="#Allegrocl_nn8">Foreign Wrappers</a> -<li><a href="#Allegrocl_nn9">FFI Wrappers</a> -<li><a href="#Allegrocl_nn10">Non-overloaded Defuns</a> -<li><a href="#Allegrocl_nn11">Overloaded Defuns</a> -<li><a href="#Allegrocl_nn12">What about constant and variable access?</a> -<li><a href="#Allegrocl_nn13">Object Wrapping</a> -</ul> -<li><a href="#Allegrocl_nn14">Wrapping Details</a> -<ul> -<li><a href="#Allegrocl_nn15">Namespaces</a> -<li><a href="#Allegrocl_nn16">Constants</a> -<li><a href="#Allegrocl_nn17">Variables</a> -<li><a href="#Allegrocl_nn18">Enumerations</a> -<li><a href="#Allegrocl_nn19">Arrays</a> -<li><a href="#Allegrocl_nn20">Classes and Structs and Unions (oh my!)</a> -<ul> -<li><a href="#Allegrocl_nn21">CLOS wrapping of</a> -<li><a href="#Allegrocl_nn22">CLOS Inheritance</a> -<li><a href="#Allegrocl_nn23">Member fields and functions</a> -<li><a href="#Allegrocl_nn24">Why not directly access C++ classes using foreign types?</a> -</ul> -<li><a href="#Allegrocl_nn25">Templates</a> -<ul> -<li><a href="#Allegrocl_nn26">Generating wrapper code for templates</a> -<li><a href="#Allegrocl_nn27">Implicit Template instantiation</a> -</ul> -<li><a href="#Allegrocl_nn28">Typedef, Templates, and Synonym Types</a> -<ul> -<li><a href="#Allegrocl_nn29">Choosing a primary type</a> -</ul> -<li><a href="#Allegrocl_nn30">Function overloading/Parameter defaulting</a> -<li><a href="#Allegrocl_nn31">Operator wrapping and Operator overloading</a> -<li><a href="#Allegrocl_nn32">Varargs</a> -<li><a href="#Allegrocl_nn33">C++ Exceptions</a> -<li><a href="#Allegrocl_nn34">Pass by value, pass by reference</a> -</ul> -<li><a href="#Allegrocl_nn35">Typemaps</a> -<ul> -<li><a href="#Allegrocl_nn36">Code Generation in the C++ Wrapper</a> -<ul> -<li><a href="#Allegrocl_nn37">IN Typemap</a> -<li><a href="#Allegrocl_nn38">OUT Typemap</a> -<li><a href="#Allegrocl_nn39">CTYPE Typemap</a> -</ul> -<li><a href="#Allegrocl_nn40">Code generation in Lisp wrappers</a> -<ul> -<li><a href="#Allegrocl_nn41">LIN Typemap</a> -<li><a href="#Allegrocl_nn42">LOUT Typemap</a> -<li><a href="#Allegrocl_nn43">FFITYPE Typemap</a> -<li><a href="#Allegrocl_nn44">LISPTYPE Typemap</a> -<li><a href="#Allegrocl_nn45">LISPCLASS Typemap</a> -</ul> -<li><a href="#Allegrocl_nn46">Modifying SWIG behavior using typemaps</a> -</ul> -<li><a href="#Allegrocl_nn47">Identifier Converter functions</a> -<ul> -<li><a href="#Allegrocl_nn48">Creating symbols in the lisp environment</a> -<li><a href="#Allegrocl_nn49">Existing identifier-converter functions</a> -<ul> -<li><a href="#Allegrocl_nn50">identifier-convert-null</a> -<li><a href="#Allegrocl_nn51">identifier-convert-lispify</a> -<li><a href="#Allegrocl_nn52">Default identifier to symbol conversions</a> -</ul> -<li><a href="#Allegrocl_nn53">Defining your own identifier-converter</a> -<li><a href="#Allegrocl_nn54">Instructing SWIG to use a particular identifier-converter</a> -</ul> -</ul> -</div> -<!-- INDEX --> - - - -<p> -This chapter describes SWIG's support of Allegro Common Lisp. Allegro -CL is a full-featured implementation of the Common Lisp language -standard that includes many vendor-specific enhancements and add-on -modules for increased usability. -</p> - -<p> -One such module included in Allegro CL is the Foreign Functions -Interface (FFI). This module, tailored primarily toward interfacing -with C/C++ and, historically, Fortran, provides a means by which -compiled foreign code can be loaded into a running lisp -environment and executed. The interface supports the calling of -foreign functions and methods, allows for executing lisp routines -from foreign code (callbacks), and the passing of data between foreign -and lisp code. -</p> - -<p> -The goal of this module is to make it possible to quickly generate the -necessary foreign function definitions so one can make use of C/C++ -foreign libraries directly from lisp without the tedium of having to -code them by hand. When necessary, it will also generate further C/C++ -code that will need to be linked with the intended library for proper -interfacing from lisp. It has been designed with an eye toward -flexibility. Some foreign function calls may release the heap, while -other should not. Some foreign functions should automatically convert -lisp strings into native strings, while others should not. These -adjustments and many more are possible with the current module. -</p> - -<p> -It is significant to note that, while this is a vendor-specific -module, we would like to acknowledge the current and ongoing -work by developers in the open source lisp community that are -working on similar interfaces to implementation-independent -foreign function interfaces (CFFI, for example). Such -work can only benefit the lisp community, and we would not -be unhappy to see some enterprising folk use this work to add -to it. -</p> - -<H2><a name="Allegrocl_nn2">20.1 Basics</a></H2> - - -<H3><a name="Allegrocl_nn3">20.1.1 Running SWIG</a></H3> - - -<p> -If you're reading this, you must have some library you need to -generate an interface for. In order for SWIG to do this work, however, -it needs a bit of information about how it should go about creating -your interface, and what you are interfacing to. -</p> - -<p> -SWIG expects a description of what in the foreign interface you wish -to connect to. It must consisting of C/C++ declarations and special -SWIG directives. SWIG can be furnished with a header file, but an -interface can also be generated without library headers by supplying a -simple text file--called the interface file, which is typically named -with a <tt>.i</tt> extension--containing any foreign declarations of -identifiers you wish to use. The most common approach is to use an -interface file with directives to parse the needed headers. A straight -parse of library headers will result in usable code, but SWIG -directives provides much freedom in how a user might tailor the -generated code to their needs or style of coding. -</p> - -<p> -Note that SWIG does not require any function definitions; the -declarations of those functions is all that is necessary. Be careful -when tuning the interface as it is quite possible to generate code -that will not load or compile. -</p> - -<p> -An example interface file is shown below. It makes use of two SWIG -directives, one of which requests that the declarations in a header -file be used to generate part of the interface, and also includes an -additional declaration to be added.</p> - -<div class="code">example.i -<pre> -%module example - -%include "header.h" - -int fact(int n); -</pre> -</div> - -<p>The contents of header.h are very simple:</p> -<div class="code">header.h -<pre> -int fact(char *statement); // pass it a fact, and it will rate it. -</pre> -</div> - -<p>The contents of example.cl will look like this:</p> - -<div class="targetlang">example.cl -<pre> -(defpackage :example - (:use :common-lisp :swig :ff :excl)) - - ... helper routines for defining the interface ... - -(swig-in-package ()) - -(swig-defun ("fact") - ((PARM0_statement cl:string (* :char) )) - (:returning (:int ) - :strings-convert t) - (let ((SWIG_arg0 PARM0_statement)) - (swig-ff-call SWIG_arg0))) - -(swig-defun ("fact") - ((PARM0_n cl:integer :int )) - (:returning (:int ) - :strings-convert t) - (let ((SWIG_arg0 PARM0_n)) - (swig-ff-call SWIG_arg0))) - -(swig-dispatcher ("fact" :type :function :arities (1))) -</pre> -</div> - -<p> -The generated file contains calls to internal swig helper -functions. In this case there are two calls to swig-defun. -These calls will expand into code that will make the appropriate -definitions using the Allegro FFI. Note also, that this code is -<b>erroneous</b>. Function overloading is not supported in C, and this -code will not compile even though SWIG did not complain. -</p> - -<p> -In order to generate a C interface to Allegro CL using this code run -swig using the <tt>-allegrocl</tt> option, as below: -</p> - -<div class="shell"> -<pre> -% swig -allegrocl example.i -</pre> -</div> - -<p> -When building an interface to C++ code, include the <tt>-c++</tt> option: -</p> - -<div class="shell"> -<pre> -% swig -allegrocl -c++ example.i -</pre> -</div> - -<p> -As a result of running one of the above commands, a file named <tt>example.cl</tt> -will be generated containing the lisp side of the interface. As well, a file -<tt>example_wrap.cxx</tt> is also generated, containing C/C++ wrapper code to -facilitate access to C++ methods, enumeration values, and constant values. -Wrapper functions are necessary in C++ due to the lack of a standard for mangling -the names of symbols across all C++ compilers. These wrapper functions are -exported from the shared library as appropriate, using the C name mangling -convention. The lisp code that is generated will interface to your foreign -library through these wrappers. -</p> - -<p> -It is possible to disable the creation of the .cxx file when generating a C -interface by using the -nocwrap command-line argument. For interfaces that -don't contain complex enum or constant expressions, contain nested struct/union -declarations, or doesn't need to use many of the SWIG customization featuers, -this will result in a more streamlined, direct interface to the -intended module. -</p> - -<p> -The generated wrapper file is below. It contains very simple -wrappers by default, that simply pass the arguments to the -actual function. -</p> - -<div class="code">example_wrap.i -<pre> - ... lots of SWIG internals ... - -EXPORT int ACL___fact__SWIG_0 (char *larg1) { - int lresult = (int)0 ; - char *arg1 = (char *) 0 ; - int result; - - arg1 = larg1; - try { - result = (int)fact(arg1); - - lresult = result; - return lresult; - } catch (...) { - return (int)0; - } -} - - -EXPORT int ACL___fact__SWIG_1 (int larg1) { - int lresult = (int)0 ; - int arg1 ; - int result; - - arg1 = larg1; - try { - result = (int)fact(arg1); - - lresult = result; - return lresult; - } catch (...) { - return (int)0; - } -} -</pre> -</div> - -<p> -And again, the generated lisp code. Note that it differs from -what is generated when parsing C code: -</p> - -<div class="targetlang"> -<pre> - ... - -(swig-in-package ()) - -(swig-defmethod ("fact" "ACL___fact__SWIG_0" :type :function :arity 1) - ((PARM0_statement cl:string (* :char) )) - (:returning (:int ) - :strings-convert t) - (let ((SWIG_arg0 PARM0_statement)) - (swig-ff-call SWIG_arg0))) - -(swig-defmethod ("fact" "ACL___fact__SWIG_1" :type :function :arity 1) - ((PARM0_n cl:integer :int )) - (:returning (:int ) - :strings-convert t) - (let ((SWIG_arg0 PARM0_n)) - (swig-ff-call SWIG_arg0))) - -(swig-dispatcher ("fact" :type :function :arities (1))) -</pre> -</div> - -<p>In this case, the interface generates two swig-defmethod forms and -a swig-dispatcher form. This provides a single functional interface for -all overloaded routines. A more detailed description of this features -is to be found in the section titled <b>Function overloading/Parameter defaulting</b>. - -<p> -In order to load a C++ interface, you will need to build a shared library -from example_wrap.cxx. Be sure to link in the actual library you created -the interface for, as well as any other dependent shared libraries. For -example, if you intend to be able to call back into lisp, you will also -need to link in the Allegro shared library. The library you create from -the C++ wrapper will be what you then load into Allegro CL. -</p> - -<H3><a name="Allegrocl_nn4">20.1.2 Command Line Options</a></H3> - - -<p> -There are three Allegro CL specific command-line option: -</p> - -<div class="shell"> -<pre> -swig -allegrocl [ options ] filename - - -identifier-converter [name] - Binds the variable swig:*swig-identifier-convert* - in the generated .cl file to <tt>name</tt>. - This function is used to generate symbols - for the lisp side of the interface. - - -cwrap - [default] Generate a .cxx file containing C wrapper function when - wrapping C code. The interface generated is similar to what is - done for C++ code. - -nocwrap - Explicitly turn off generation of .cxx wrappers for C code. Reasonable - for modules with simple interfaces. Can not handle all legal enum - and constant constructs, or take advantage of SWIG customization features. - - -isolate - With this command-line argument, all lisp helper functions are defined - in a unique package named <tt>swig.<module-name></tt> rather than - <tt>swig</tt>. This prevents conflicts when the module is - intended to be used with other swig generated interfaces that may, - for instance, make use of different identifier converters. -</pre> -</div> - -<p> -See <a href="#Allegrocl_nn47">Section 17.5 Identifier converter -functions</a> for more details. -</p> - -<H3><a name="Allegrocl_nn5">20.1.3 Inserting user code into generated files</a></H3> - - -<p> -It is often necessary to include user-defined code into the -automatically generated interface files. For example, when building -a C++ interface, example_wrap.cxx will likely not compile unless -you add a <tt>#include "header.h"</tt> directive. This can be done -using the SWIG <tt>%insert(section) %{ ...code... %}</tt> directive: -</p> - -<div class="code"> -<pre> -%module example - -%{ -#include "header.h" -%} - -%include "header.h" - -int fact(int n); -</pre> -</div> - -<p> -Additional sections have been added for inserting into the -generated lisp interface file -</p> -<ul> - <li><tt>lisphead</tt> - inserts before type declarations</li> - <li><tt>lisp</tt> - inserts after type declarations according to - where it appears in the .i file</li> -</ul> -<p> -Note that the block <tt>%{ ... %}</tt> is effectively a shortcut for -<tt>%insert("header") %{ ... %}</tt>. -</p> - - -<H2><a name="Allegrocl_nn6">20.2 Wrapping Overview</a></H2> - - -<p> -New users to SWIG are encouraged to read -<a href="SWIG.html#SWIG">SWIG Basics</a>, and -<a href="SWIGPlus.html#SWIGPlus">SWIG and C++</a>, for those -interested in generating an interface to C++. -</p> - -<H3><a name="Allegrocl_nn7">20.2.1 Function Wrapping</a></H3> - - - <p> - Writing lisp code that directly invokes functions at the foreign - function interface level can be cumbersome. Data must often be - translated between lisp and foreign types, data extracted from - objects, foreign objects allocated and freed upon completion of - the foreign call. Dealing with pointers can be unwieldy when it - comes to keeping them distinct from other valid integer values. - </p> - - <p> - We make an attempt to ease some of these burdens by making the - interface to foreign code much more lisp-like, rather than C - like. How this is done is described in later chapters. The - layers themselves, appear as follows: - </p> - - <div class="diagram"> - <pre> - ______________ - | | (foreign side) - | Foreign Code | What we're generating an interface to. - |______________| - | - | - _______v______ - | | (foreign side) - | Wrapper code | extern "C" wrappers calling C++ - |______________| functions and methods. - | - . . . - - + - - . . . - _______v______ - | | (lisp side) - | FFI Layer | Low level lisp interface. ff:def-foreign-call, - |______________| ff:def-foreign-variable - | - +---------------------------- - _______v______ _______v______ - | | | | (lisp side) - | Defuns | | Defmethods | wrapper for overloaded - |______________| |______________| functions or those with - (lisp side) | defaulted arguments - Wrapper for non-overloaded | - functions and methods _______v______ - | | (lisp side) - | Defuns | dispatch function - |______________| to overloads based - on arity - </pre> - </div> - -<H3><a name="Allegrocl_nn8">20.2.2 Foreign Wrappers</a></H3> - - - <p> - These wrappers are as generated by SWIG default. The types of - function parameters can be transformed in place using the CTYPE - typemap. This is use for converting pass-by-value parameters to - pass-by-reference where necessary. All wrapper parameters are then - bound to local variables for possible transformation of values - (see LIN typemap). Return values can be transformed via the OUT - typemap. - </p> - -<H3><a name="Allegrocl_nn9">20.2.3 FFI Wrappers</a></H3> - - - <p> - These are the generated ff:def-foreign-call forms. No typemaps are - applicable to this layer, but the <tt>%ffargs</tt> directive is - available for use in .i files, to specify which keyword arguments - should be specified for a given function. - </p> - - <div class="code">ffargs.i: - <pre> -%module ffargs - -%ffargs(strings_convert="nil", call_direct="t") foo; -%ffargs(strings_convert="nil", release_heap=":never", optimize_for_space="t") bar; - -int foo(float f1, float f2); -int foo(float f1, char c2); - -void bar(void *lisp_fn); - -char *xxx(); - </pre> - </div> - - <p>Generates: - </p> - <div class="targetlang">ffargs.cl: - <pre> -(swig-in-package ()) - -(swig-defmethod ("foo" "ACL___foo__SWIG_0" :type :function :arity 2) - ((PARM0_f1 cl:single-float :float ) - (PARM1_f2 cl:single-float :float )) - (:returning (:int ) - :call-direct t - :strings-convert nil) - (let ((SWIG_arg0 PARM0_f1)) - (let ((SWIG_arg1 PARM1_f2)) - (swig-ff-call SWIG_arg0 SWIG_arg1)))) - -(swig-defmethod ("foo" "ACL___foo__SWIG_1" :type :function :arity 2) - ((PARM0_f1 cl:single-float :float ) - (PARM1_c2 cl:character :char character)) - (:returning (:int ) - :call-direct t - :strings-convert nil) - (let ((SWIG_arg0 PARM0_f1)) - (let ((SWIG_arg1 PARM1_c2)) - (swig-ff-call SWIG_arg0 SWIG_arg1)))) - -(swig-dispatcher ("foo" :type :function :arities (2))) -(swig-defun ("bar" "ACL___bar__SWIG_0" :type :function) - ((PARM0_lisp_fn (* :void) )) - (:returning (:void ) - :release-heap :never - :optimize-for-space t - :strings-convert nil) - (let ((SWIG_arg0 PARM0_lisp_fn)) - (swig-ff-call SWIG_arg0))) - - -(swig-defun ("xxx" "ACL___xxx__SWIG_0" :type :function) - (:void) - (:returning ((* :char) ) - :strings-convert t) - (swig-ff-call)) - </pre> - </div> - - <div class="code"> - <pre>%ffargs(strings_convert="t");</pre> - </div> - - <p> - Is the only default value specified in <tt>allegrocl.swg</tt> to force - the muffling of warnings about automatic string conversion when defining - ff:def-foreign-call's. - </p> - -<H3><a name="Allegrocl_nn10">20.2.4 Non-overloaded Defuns</a></H3> - - - <p> - These are simple defuns. There is no typechecking of arguments. - Parameters are bound to local variables for possible - transformation of values, such as pulling values out of instance - slots or allocating temporary stack allocated structures, via the - <tt>lin</tt> typemap. These arguments are then passed to the - foreign-call (where typechecking may occur). The return value from - this function can be manipulated via the <tt>lout</tt> typemap. - </p> - -<H3><a name="Allegrocl_nn11">20.2.5 Overloaded Defuns</a></H3> - - - <p> - In the case of overloaded functions, multiple layers are - generated. First, all the overloads for a given name are separated - out into groups based on arity, and are wrapped in - defmethods. Each method calls a distinct wrapper function, but are - themselves distinguished by the types of their arguments - (see <tt>lispclass</tt> typemap). These are further wrapped in a - dispatching function (defun) which will invoke the appropriate - generic-function based on arity. This provides a single functional - interface to all overloads. The return value from this function - can be manipulated via the <tt>lout</tt> typemap. - </p> - -<H3><a name="Allegrocl_nn12">20.2.6 What about constant and variable access?</a></H3> - - - <p> - Along with the described functional layering, when creating a .cxx wrapper, - this module will generate getter and--if not immutable--setter, - functions for variables and constants. If the -nocwrap option is used, - <tt>defconstant</tt> and <tt>ff:def-foreign-variable</tt> forms will be - generated for accessing constants and global variables. These, along with - the <tt>defuns</tt> listed above are the intended API for calling - into the foreign module. - </p> - -<H3><a name="Allegrocl_nn13">20.2.7 Object Wrapping</a></H3> - - - <p> - All non-primitive types (Classes, structs, unions, and typedefs - involving same) have a corresponding foreign-type defined on the - lisp side via ff:def-foreign-type. - </p> - - <p> - All non-primitive types are further represented by a CLOS class, - created via defclass. An attempt is made to create the same class - hierarchy, with all classes inheriting directly or indirectly from - ff:foreign-pointer. Further, wherever it is apparent, all pointers - returned from foreign code are wrapped in a CLOS instance of the - appropriate class. For ff:def-foreign-calls that have been defined - to expect a :foreign-address type as argument, these CLOS instances - can legally be passed and the pointer to the C++ object - automatically extracted. This is a natural feature of Allegro's - foreign function interface. - </p> - -<H2><a name="Allegrocl_nn14">20.3 Wrapping Details</a></H2> - - - <p> - In this section is described how particular C/C++ constructs are - translated into lisp. - </p> - -<H3><a name="Allegrocl_nn15">20.3.1 Namespaces</a></H3> - - - <p> - C++ namespaces are translated into Lisp packages by SWIG. The - Global namespace is mapped to a package named by the <tt>%module</tt> - directive or the <tt>-module</tt> command-line argument. Further - namespaces are generated by the <tt>swig-defpackage</tt> utility - function and given names based on Allegro CLs nested namespace - convention. For example: - </p> - - <div class="code">foo.i: - <pre> -%module foo - -%{ -#include "foo.h" -%} - -%include "foo.h" - -namespace car { - ... - namespace tires { - int do_something(int n); - } -} - </pre> - </div> - <p>Generates the following code. - </p> - <div class="targetlang">foo.cl - <pre> -(defpackage :foo - (:use :common-lisp :swig :ff :excl)) - -... - -(swig-defpackage ("car")) -(swig-defpackage ("car" "tires")) - -... - -(swig-in-package ("car" "tires")) -(swig-defun ("do_something" "ACL_car_tires__do_something__SWIG_0" :type :function) - ((PARM0_n :int )) - (:returning (:int ) - :strings-convert t) - (let ((SWIG_arg0 PARM0_n)) - (swig-ff-call SWIG_arg0))) - </pre> - </div> - - <p> - The above interface file would cause packages foo, foo.car, and - foo.car.tires to be created. One would find the function wrapper - for do_something defined in the foo.car.tires package(*). - </p> - - <p>(<b>*</b>) Except for the package named by the module, all - namespace names are passed to the identifier-converter-function - as strings with a <tt>:type</tt> of <tt>:namespace</tt>. It is the - job of this function to generate the desired symbol, accounting for - case preferences, additional naming cues, etc. - </p> - - <p> - Note that packages created by <tt>swig-defpackage</tt> do not - use the COMMON-LISP or EXCL package. This reduces possible - conflicts when defining foreign types via the SWIG interface - in <b>all but the toplevel modules package</b>. This may - lead to confusion if, for example, the current package is - <tt>foo.car.tires</tt> and you attempt to use a common-lisp - function such as <tt>(car '(1 2 3)</tt>. - </p> - -<H3><a name="Allegrocl_nn16">20.3.2 Constants</a></H3> - - - - <p> - Constants, as declared by the preprocessor #define macro or SWIG - <tt>%constant</tt> directive, are included in SWIG's parse tree - when it can be determined that they are, or could be reduced to, - a literal value. Such values are translated into defconstant - forms in the generated lisp wrapper when the -nocwrap command-line - options is used. Else, wrapper functions are generated as in the - case of variable access (see section below). - </p> - <p> - Here are examples of simple preprocessor constants when using -nocwrap. - </p> - <div class="code"> - <pre> -#define A 1 => (swig-defconstant "A" 1) -#define B 'c' => (swig-defconstant "B" #\c) -#define C B => (swig-defconstant "C" #\c) -#define D 1.0e2 => (swig-defconstant "D" 1.0d2) -#define E 2222 => (swig-defconstant "E" 2222) -#define F (unsigned int)2222 => no code generated -#define G 1.02e2f => (swig-defconstant "G" 1.02f2) -#define H foo => no code generated - </pre> - </div> - - <p> - Note that where SWIG is unable to determine if a constant is - a literal, no node is added to the SWIG parse tree, and so - no values can be generated. - </p> - - <p> - For preprocessor constants containing expressions which can be - reduced to literal values, nodes are created, but with no simplification - of the constant value. A very very simple infix to prefix converter - has been implemented that tries to do the right thing for simple cases, but - does not for more complex expressions. If the literal parser determines - that something is wrong, a warning will be generated and the literal - expression will be included in the generated code, but commented out. - </p> - - <div class="code"> - <pre> -#define I A + E => (swig-defconstant "I" (+ 1 2222)) -#define J 1|2 => (swig-defconstant "J" (logior 1 2)) -#define Y 1 + 2 * 3 + 4 => (swig-defconstant "Y" (* (+ 1 2) (+ 3 4))) -#define Y1 (1 + 2) * (3 + 4) => (swig-defconstant "Y1" (* (+ 1 2) (+ 3 4))) -#define Y2 1 * 2 + 3 * 4 => (swig-defconstant "Y2" (* 1 (+ 2 3) 4)) ;; WRONG -#define Y3 (1 * 2) + (3 * 4) => (swig-defconstant "Y3" (* 1 (+ 2 3) 4)) ;; WRONG -#define Z 1 + 2 - 3 + 4 * 5 => (swig-defconstant "Z" (* (+ 1 (- 2 3) 4) 5)) ;; WRONG - </pre> - </div> - <p> - Users are cautioned to get to know their constants before use, or - not use the <tt>-nocwrap</tt> command-line option. - </p> - -<H3><a name="Allegrocl_nn17">20.3.3 Variables</a></H3> - - - <p> - For C wrapping, a def-foreign-variable call is generated for access - to global variables. - </p> - <p> - When wrapping C++ code, both global and member variables, getter - wrappers are generated for accessing their value, and if not immutable, - setter wrappers as well. In the example below, note the lack of a - setter wrapper for global_var, defined as const. - </p> - - <div class="code">vars.h - <pre> -namespace nnn { - int const global_var = 2; - float glob_float = 2.0; -} - </pre> - </div> - - <p> - Generated code: - </p> - <div class="targetlang">vars.cl - <pre> -(swig-in-package ("nnn")) -(swig-defun ("global_var" "ACL_nnn__global_var_get__SWIG_0" :type :getter) - (:void) - (:returning (:int ) - :strings-convert t) - (swig-ff-call)) - - -(swig-defun ("glob_float" "ACL_nnn__glob_float_set__SWIG_0" :type :setter) - ((PARM0_glob_float :float )) - (:returning (:void ) - :strings-convert t) - (let ((SWIG_arg0 PARM0_glob_float)) - (swig-ff-call SWIG_arg0))) - - -(swig-defun ("glob_float" "ACL_nnn__glob_float_get__SWIG_0" :type :getter) - (:void) - (:returning (:float ) - :strings-convert t) - (swig-ff-call)) - </pre> - </div> - - <p> - Note also, that where applicable, setter wrappers are implemented - as setf methods on the getter function, providing a lispy interface - to the foreign code. - </p> - - <div class="targetlang"> - <pre> -user> (load "globalvar.dll") -; Foreign loading globalvar.dll. -t -user> (load "globalvar.cl") -; Loading c:\mikel\src\swig\test\globalvar.cl -t -user> -globalvar> (globalvar.nnn::global_var) -2 -globalvar> (globalvar.nnn::glob_float) -2.0 -globalvar> (setf (globalvar.nnn::glob_float) 3.0) -3.0 -globalvar> (globalvar.nnn::glob_float) -3.0 - </pre> - </div> - -<H3><a name="Allegrocl_nn18">20.3.4 Enumerations</a></H3> - - - <p> - In C, an enumeration value is an integer value, while in C++ an - enumeration value is implicitly convertible to an integer value, - but can also be distinguished by its enum type. For each enum - declaration a def-foreign-type is generated, assigning the enum - a default type of :int. Users may adjust the foreign type of - enums via SWIG <tt>typemaps</tt>. - </p> - - <p> - Enum values are a bit trickier as they can be initialized using - any valid C/C++ expression. In C with the -nocwrap command-line option, - we handle the typical cases (simple integer initialization) and - generate a defconstant form for each enum value. This has the advantage - of it not being necessary to probe into foreign space to retrieve enum - values. When generating a .cxx wrapper file, a more general solution is - employed. A wrapper variable is created in the module_wrap.cxx file, and - a ff:def-foreign-variable call is generated to retrieve its value into lisp. - </p> - - <p>For example, the following header file - <div class="code">enum.h: - <pre> -enum COL { RED, GREEN, BLUE }; -enum FOO { FOO1 = 10, FOO2, FOO3 }; - </pre> - </div> - <p> - In -nocwrap mode, generates - </p> - <div class="targetlang">enum.cl: - <pre> -(swig-def-foreign-type "COL" :int) -(swig-defconstant "RED" 0) -(swig-defconstant "GREEN" (+ #.(swig-insert-id "RED" () :type :constant) 1)) -(swig-defconstant "BLUE" (+ #.(swig-insert-id "GREEN" () :type :constant) 1)) - -(swig-def-foreign-type "FOO" :int) -(swig-defconstant "FOO1" 10) -(swig-defconstant "FOO2" (+ #.(swig-insert-id "FOO1" () :type :constant) 1)) -(swig-defconstant "FOO3" (+ #.(swig-insert-id "FOO2" () :type :constant) 1)) - </pre> - </div> - - <p>And when generating a .cxx wrapper - <div class="code">enum_wrap.cxx: - <pre> -EXPORT const int ACL_ENUM___RED__SWIG_0 = RED; -EXPORT const int ACL_ENUM___GREEN__SWIG_0 = GREEN; -EXPORT const int ACL_ENUM___BLUE__SWIG_0 = BLUE; -EXPORT const int ACL_ENUM___FOO1__SWIG_0 = FOO1; -EXPORT const int ACL_ENUM___FOO2__SWIG_0 = FOO2; -EXPORT const int ACL_ENUM___FOO3__SWIG_0 = FOO3; - </pre> - </div> - <p> - and - </p> - <div class="targetlang">enum.cl: - <pre> -(swig-def-foreign-type "COL" :int) -(swig-defvar "RED" "ACL_ENUM___RED__SWIG_0" :type :constant) -(swig-defvar "GREEN" "ACL_ENUM___GREEN__SWIG_0" :type :constant) -(swig-defvar "BLUE" "ACL_ENUM___BLUE__SWIG_0" :type :constant) - -(swig-def-foreign-type "FOO" :int) -(swig-defvar "FOO1" "ACL_ENUM___FOO1__SWIG_0" :type :constant) -(swig-defvar "FOO2" "ACL_ENUM___FOO2__SWIG_0" :type :constant) -(swig-defvar "FOO3" "ACL_ENUM___FOO3__SWIG_0" :type :constant) - - </pre> - </div> - -<H3><a name="Allegrocl_nn19">20.3.5 Arrays</a></H3> - - - <p> - One limitation in the Allegro CL foreign-types module, is that, - without macrology, expressions may not be used to specify the - dimensions of an array declaration. This is not a horrible - drawback unless it is necessary to allocate foreign structures - based on the array declaration using ff:allocate-fobject. When it - can be determined that an array bound is a valid numeric value, - SWIG will include this in the generated array declaration on the - lisp side, otherwise the value will be included, but commented out. - </p> - - <p> - Below is a comprehensive example, showing a number of legal - C/C++ array declarations and how they are translated - into foreign-type specifications in the generated lisp code. - </p> - <div class="code">array.h - <pre> -#define MAX_BUF_SIZE 1024 - -namespace FOO { - int global_var1[13]; - float global_var2[MAX_BUF_SIZE]; - -} - -enum COLOR { RED = 10, GREEN = 20, BLUE, PURPLE = 50, CYAN }; - -namespace BAR { - char global_var3[MAX_BUF_SIZE + 1]; - float global_var4[MAX_BUF_SIZE][13]; - signed short global_var5[MAX_BUF_SIZE + MAX_BUF_SIZE]; - - int enum_var5[GREEN]; - int enum_var6[CYAN]; - - COLOR enum_var7[CYAN][MAX_BUF_SIZE]; -} - </pre> - </div> - - <p> - Generates: - </p> - - <div class="targetlang">array.cl - <pre> -(in-package #.*swig-module-name*) - -(swig-defpackage ("FOO")) -(swig-defpackage ("BAR")) - -(swig-in-package ()) -(swig-def-foreign-type "COLOR" :int) -(swig-defvar "RED" "ACL_ENUM___RED__SWIG_0" :type :constant) -(swig-defvar "GREEN" "ACL_ENUM___GREEN__SWIG_0" :type :constant) -(swig-defvar "BLUE" "ACL_ENUM___BLUE__SWIG_0" :type :constant) -(swig-defvar "PURPLE" "ACL_ENUM___PURPLE__SWIG_0" :type :constant) -(swig-defvar "CYAN" "ACL_ENUM___CYAN__SWIG_0" :type :constant) - -(swig-in-package ()) - -(swig-defconstant "MAX_BUF_SIZE" 1024) -(swig-in-package ("FOO")) - -(swig-defun ("global_var1" "ACL_FOO__global_var1_get__SWIG_0" :type :getter) - (:void) - (:returning ((* :int) ) - :strings-convert t) - (make-instance 'ff:foreign-pointer :foreign-address (swig-ff-call))) - - -(swig-defun ("global_var2" "ACL_FOO__global_var2_set__SWIG_0" :type :setter) - ((global_var2 (:array :float 1024) )) - (:returning (:void ) - :strings-convert t) - (let ((SWIG_arg0 global_var2)) - (swig-ff-call SWIG_arg0))) - - -(swig-in-package ()) -(swig-in-package ("BAR")) -(swig-defun ("global_var3" "ACL_BAR__global_var3_set__SWIG_0" :type :setter) - ((global_var3 (:array :char #|1024+1|#) )) - (:returning (:void ) - :strings-convert t) - (let ((SWIG_arg0 global_var3)) - (swig-ff-call SWIG_arg0))) - - -(swig-defun ("global_var4" "ACL_BAR__global_var4_set__SWIG_0" :type :setter) - ((global_var4 (:array (:array :float 13) 1024) )) - (:returning (:void ) - :strings-convert t) - (let ((SWIG_arg0 global_var4)) - (swig-ff-call SWIG_arg0))) - - -(swig-defun ("global_var4" "ACL_BAR__global_var4_get__SWIG_0" :type :getter) - (:void) - (:returning ((* (:array :float 13)) ) - :strings-convert t) - (make-instance 'ff:foreign-pointer :foreign-address (swig-ff-call))) - - -(swig-defun ("global_var5" "ACL_BAR__global_var5_set__SWIG_0" :type :setter) - ((global_var5 (:array :short #|1024+1024|#) )) - (:returning (:void ) - :strings-convert t) - (let ((SWIG_arg0 global_var5)) - (swig-ff-call SWIG_arg0))) - - -(swig-defun ("enum_var5" "ACL_BAR__enum_var5_set__SWIG_0" :type :setter) - ((enum_var5 (:array :int #|GREEN|#) )) - (:returning (:void ) - :strings-convert t) - (let ((SWIG_arg0 enum_var5)) - (swig-ff-call SWIG_arg0))) - - -(swig-defun ("enum_var6" "ACL_BAR__enum_var6_set__SWIG_0" :type :setter) - ((enum_var6 (:array :int #|CYAN|#) )) - (:returning (:void ) - :strings-convert t) - (let ((SWIG_arg0 enum_var6)) - (swig-ff-call SWIG_arg0))) - - -(swig-defun ("enum_var7" "ACL_BAR__enum_var7_set__SWIG_0" :type :setter) - ((enum_var7 (:array (:array #.(swig-insert-id "COLOR" ()) 1024) #|CYAN|#) )) - (:returning (:void ) - :strings-convert t) - (let ((SWIG_arg0 enum_var7)) - (swig-ff-call SWIG_arg0))) - - -(swig-defun ("enum_var7" "ACL_BAR__enum_var7_get__SWIG_0" :type :getter) - (:void) - (:returning ((* (:array #.(swig-insert-id "COLOR" ()) 1024)) ) - :strings-convert t) - (make-instance 'ff:foreign-pointer :foreign-address (swig-ff-call))) - </pre> - </div> - -<H3><a name="Allegrocl_nn20">20.3.6 Classes and Structs and Unions (oh my!)</a></H3> - - -<H4><a name="Allegrocl_nn21">20.3.6.1 CLOS wrapping of</a></H4> - - - <p> - Classes, unions, and structs are all treated the same way by the - interface generator. For any of these objects, a - def-foreign-type and a defclass form are generated. For every - function that returns an object (or pointer/reference) of C/C++ - type <tt>X</tt>, the wrapping defun (or defmethod) on the Lisp - side will automatically wrap the pointer returned in an instance - of the appropriate class. This makes it much easier to write and - debug code than if pointers were passed around as a jumble of - integer values. - </p> - -<H4><a name="Allegrocl_nn22">20.3.6.2 CLOS Inheritance</a></H4> - - - <p> - The CLOS class schema generated by the interface mirrors the - inheritance of the classes in foreign code, with the - ff:foreign-pointer class at its root. ff:foreign-pointer is a thin - wrapper for pointers that is made available by the foreign function - interface. Its key benefit is that it may be passed as an argument - to any ff:def-foreign-call that is expecting a pointer as the - parameter. - </p> - -<H4><a name="Allegrocl_nn23">20.3.6.3 Member fields and functions</a></H4> - - - <p> - All public fields will have accessor getter/setter functions - generated for them, as appropriate. All public member functions - will have wrapper functions generated. - </p> - - <p> - We currently ignore anything that isn't <tt>public</tt> (i.e. - <tt>private</tt> or <tt>protected</tt>), because the C++ compiler - won't allow the wrapper functions to access such fields. Likewise, - the interface does nothing for <tt>friend</tt> directives, - </p> - -<H4><a name="Allegrocl_nn24">20.3.6.4 Why not directly access C++ classes using foreign types?</a></H4> - - - <p> - The def-foreign-type generated by the SWIG interface is - currently incomplete. We can reliably generate the object layout - of simple structs and unions; they can be allocated via - ff:allocate-fobject, and their member variables accessed - directly using the various ff:fslot-value-* functions. However, - the layout of C++ classes is more complicated. Different - compilers adjust class layout based on inheritance patterns, and - the presence of virtual member functions. The size of member - function pointers vary across compilers as well. As a result, it - is recommended that users of any generated interface not attempt - to access C++ instances via the foreign type system, but instead - use the more robust wrapper functions. - </p> - -<H3><a name="Allegrocl_nn25">20.3.7 Templates</a></H3> - - - -<H4><a name="Allegrocl_nn26">20.3.7.1 Generating wrapper code for templates</a></H4> - - -<p> -SWIG provides support for dealing with templates, but by -default, it will not generate any member variable or function -wrappers for templated classes. In order to create these -wrappers, you need to explicitly tell SWIG to instantiate -them. This is done via the -<a href="SWIGPlus.html#SWIGPlus_nn30"><tt>%template</tt></a> -directive. -</p> - -<H4><a name="Allegrocl_nn27">20.3.7.2 Implicit Template instantiation</a></H4> - - -<p> -While no wrapper code is generated for accessing member -variables, or calling member functions, type code is generated -to include these templated classes in the foreign-type and CLOS -class schema. -</p> - -<H3><a name="Allegrocl_nn28">20.3.8 Typedef, Templates, and Synonym Types</a></H3> - - - <p> - In C/C++ it is possible, via typedef, to have many names refer to - the same <tt>type</tt>. In general, this is not a problem, though - it can lead to confusion. Assume the below C++ header file: - </p> - - <div class="code">synonyms.h - <pre> -class A { - int x; - int y; -}; - -typedef A Foo; - -A *xxx(int i); /* sets A->x = A->y = i */ -Foo *yyy(int i); /* sets Foo->x = Foo->y = i */ - -int zzz(A *inst = 0); /* return inst->x + inst->y */ - </pre> - </div> - - <p> - The function <tt>zzz</tt> is an overloaded functions; the - foreign function call to it will be wrapped in a - generic-function whose argument will be checked against a type - of <tt>A</tt>. Assuming a simple implementation, a call - to <tt>xxx(1)</tt> will return a pointer to an A object, which - will be wrapped in a CLOS instance of class <tt>A</tt>, and a - call to <tt>yyy(1)</tt> will result in a CLOS instance of - type <tt>Foo</tt> being returned. Without establishing a clear - type relationship between <tt>Foo</tt> and <tt>A</tt>, an - attempt to call <tt>zzz(yyy(1))</tt> will result in an error. - </p> - - <p> - We resolve this issue, by noting synonym relationships between - types while generating the interface. A Primary type is selected - (more on this below) from the candidate list of synonyms. For - all other synonyms, instead of generating a distinct CLOS class - definition, we generate a form that expands to: - </p> - <div class="targetlang"> - <tt>(setf (find-class <synonym>) <primary>)</tt> - </div> - <p> - The result is that all references to synonym types in foreign - code, are wrapped in the same CLOS wrapper, and, in particular, - method specialization in wrapping generic functions works as - expected. - </p> - - <p> - Given the above header file, synonym.h, a Lisp session would - appear as follows: - </p> - <div class="targetlang"> - <pre> -CL-USER> (load "synonym.dll") -; Foreign loading synonym.dll. -t -CL-USER> (load "synonym.cl") -; Loading c:\mikel\src\swig\test\synonym.cl -t -CL-USER> -synonym> (setf a (xxx 3)) -#<A nil #x3261a0 @ #x207299da> -synonym> (setf foo (yyy 10)) -#<A nil #x3291d0 @ #x2072e982> -synonym> (zzz a) -6 -synonym> (zzz foo) -20 -synonym> - </pre> - </div> - -<H4><a name="Allegrocl_nn29">20.3.8.1 Choosing a primary type</a></H4> - - - <p> - The choice of a primary type is selected by the following - criteria from a set of synonym types. - </p> - <ul> - <li> - If a synonym type has a class definition, it is the primary type. - </li> - <li> - If a synonym type is a class template and has been explicitly - instantiated via <tt>%template</tt>, it is the primary type. - </li> - <li> - For all other sets of synonymous types, the synonym which is - parsed first becomes the primary type. - </li> - </ul> - -<H3><a name="Allegrocl_nn30">20.3.9 Function overloading/Parameter defaulting</a></H3> - - - <p> - For each possible argument combination, a distinct wrapper - function is created in the .cxx file. On the Lisp side, a - generic functions is defined for each possible arity the - overloaded/defaulted call may have. Each distinct wrapper is - then called from within a defmethod on the appropriate generic - function. These are further wrapped inside a dispatch function - that checks the number of arguments it is called with and passes - them via apply to the appropriate generic-function. This allows - for a single entry point to overloaded functions on the lisp - side. - </p> - - <p>Example: - </p> - <div class="code">overload.h: - <pre> - -class A { - public: - int x; - int y; -}; - -float xxx(int i, int x = 0); /* return i * x */ -float xxx(A *inst, int x); /* return x + A->x + A->y */ - </pre> - </div> - - <p>Creates the following three wrappers, for each of the possible argument - combinations - </p> - <div class="code">overload_wrap.cxx - <pre> -EXPORT void ACL___delete_A__SWIG_0 (A *larg1) { - A *arg1 = (A *) 0 ; - - arg1 = larg1; - try { - delete arg1; - - } catch (...) { - - } -} - - -EXPORT float ACL___xxx__SWIG_0 (int larg1, int larg2) { - float lresult = (float)0 ; - int arg1 ; - int arg2 ; - float result; - - arg1 = larg1; - arg2 = larg2; - try { - result = (float)xxx(arg1, arg2); - - lresult = result; - return lresult; - } catch (...) { - return (float)0; - } -} - - -EXPORT float ACL___xxx__SWIG_1 (int larg1) { - float lresult = (float)0 ; - int arg1 ; - float result; - - arg1 = larg1; - try { - result = (float)xxx(arg1); - - lresult = result; - return lresult; - } catch (...) { - return (float)0; - } -} - - -EXPORT float ACL___xxx__SWIG_2 (A *larg1, int larg2) { - float lresult = (float)0 ; - A *arg1 = (A *) 0 ; - int arg2 ; - float result; - - arg1 = larg1; - arg2 = larg2; - try { - result = (float)xxx(arg1, arg2); - - lresult = result; - return lresult; - } catch (...) { - return (float)0; - } -} - </pre> - </div> - - <p> - And the following foreign-function-call and method definitions on the - lisp side: - </p> - <div class="targetlang">overload.cl - <pre> -(swig-defmethod ("xxx" "ACL___xxx__SWIG_0" :type :function :arity 2) - ((PARM0_i cl:integer :int ) - (PARM1_x cl:integer :int )) - (:returning (:float ) - :strings-convert t) - (let ((SWIG_arg0 PARM0_i)) - (let ((SWIG_arg1 PARM1_x)) - (swig-ff-call SWIG_arg0 SWIG_arg1)))) - -(swig-defmethod ("xxx" "ACL___xxx__SWIG_1" :type :function :arity 1) - ((PARM0_i cl:integer :int )) - (:returning (:float ) - :strings-convert t) - (let ((SWIG_arg0 PARM0_i)) - (swig-ff-call SWIG_arg0))) - -(swig-defmethod ("xxx" "ACL___xxx__SWIG_2" :type :function :arity 2) - ((PARM0_inst #.(swig-insert-id "A" () :type :class) (* #.(swig-insert-id "A" ())) ) - (PARM1_x cl:integer :int )) - (:returning (:float ) - :strings-convert t) - (let ((SWIG_arg0 PARM0_inst)) - (let ((SWIG_arg1 PARM1_x)) - (swig-ff-call SWIG_arg0 SWIG_arg1)))) - -(swig-dispatcher ("xxx" :type :function :arities (1 2))) - </pre> - </div> - - <p>And their usage in a sample lisp session: - </p> - <div class="targetlang"> - <pre> -overload> (setf a (new_A)) -#<A nil #x329268 @ #x206cf612> -overload> (setf (A_x a) 10) -10 -overload> (setf (A_y a) 20) -20 -overload> (xxx 1) -0.0 -overload> (xxx 3 10) -30.0 -overload> (xxx a 1) -31.0 -overload> (xxx a 2) -32.0 -overload> - </pre> - </div> - -<H3><a name="Allegrocl_nn31">20.3.10 Operator wrapping and Operator overloading</a></H3> - - - <p> - Wrappers to defined C++ Operators are automatically renamed, using - <tt>%rename</tt>, to the following defaults: - </p> - <div class="code"> - <pre> -/* name conversion for overloaded operators. */ -#ifdef __cplusplus -%rename(__add__) *::operator+; -%rename(__pos__) *::operator+(); -%rename(__pos__) *::operator+() const; - -%rename(__sub__) *::operator-; -%rename(__neg__) *::operator-() const; -%rename(__neg__) *::operator-(); - -%rename(__mul__) *::operator*; -%rename(__deref__) *::operator*(); -%rename(__deref__) *::operator*() const; - -%rename(__div__) *::operator/; -%rename(__mod__) *::operator%; -%rename(__logxor__) *::operator^; -%rename(__logand__) *::operator&; -%rename(__logior__) *::operator|; -%rename(__lognot__) *::operator~(); -%rename(__lognot__) *::operator~() const; - -%rename(__not__) *::operator!(); -%rename(__not__) *::operator!() const; - -%rename(__assign__) *::operator=; - -%rename(__add_assign__) *::operator+=; -%rename(__sub_assign__) *::operator-=; -%rename(__mul_assign__) *::operator*=; -%rename(__div_assign__) *::operator/=; -%rename(__mod_assign__) *::operator%=; -%rename(__logxor_assign__) *::operator^=; -%rename(__logand_assign__) *::operator&=; -%rename(__logior_assign__) *::operator|=; - -%rename(__lshift__) *::operator<<; -%rename(__lshift_assign__) *::operator<<=; -%rename(__rshift__) *::operator>>; -%rename(__rshift_assign__) *::operator>>=; - -%rename(__eq__) *::operator==; -%rename(__ne__) *::operator!=; -%rename(__lt__) *::operator<; -%rename(__gt__) *::operator>; -%rename(__lte__) *::operator<=; -%rename(__gte__) *::operator>=; - -%rename(__and__) *::operator&&; -%rename(__or__) *::operator||; - -%rename(__preincr__) *::operator++(); -%rename(__postincr__) *::operator++(int); -%rename(__predecr__) *::operator--(); -%rename(__postdecr__) *::operator--(int); - -%rename(__comma__) *::operator,(); -%rename(__comma__) *::operator,() const; - -%rename(__member_ref__) *::operator->; -%rename(__member_func_ref__) *::operator->*; - -%rename(__funcall__) *::operator(); -%rename(__aref__) *::operator[]; - </pre> - </div> - - <p> - Name mangling occurs on all such renamed identifiers, so that wrapper name - generated by <tt>B::operator=</tt> will be <tt>B___eq__</tt>, i.e. - <tt><class-or-namespace>_</tt> has been added. Users may modify - these default names by adding <tt>%rename</tt> directives in their own .i files. - </p> - - <p> - Operator overloading can be achieved by adding functions based - on the mangled names of the function. In the following example, - a class B is defined with a Operator== method defined. The - swig <tt>%extend</tt> directive is used to add an overload method - on Operator==. - </p> - - <div class="code">opoverload.h - <pre> -class B { - public: - int x; - int y; - bool operator==(B const& other) const; -}; - </pre> - </div> - - <p> - and - </p> - <div class="code">opoverload.i - <pre> -%module opoverload - -%{ -#include <fstream> -#include "opoverload.h" -%} - -%{ -bool B___eq__(B const *inst, int const x) -{ - // insert the function definition into the wrapper code before - // the wrapper for it. - // ... do stuff ... -} -%} - -%include "opoverload.h" - -%extend B { - public: - bool __eq__(int const x) const; -}; - </pre> - </div> - - <p> - Either operator can be called via a single call - to the dispatch function: - </p> - <div class="targetlang"> - <pre> -opoverload> (B___eq__ x1 x2) -nil -opoverload> (B___eq__ x1 3) -nil -opoverload> - </pre> - </div> - -<H3><a name="Allegrocl_nn32">20.3.11 Varargs</a></H3> - - - <p> - Variable length argument lists are not supported, by default. If - such a function is encountered, a warning will generated to - stderr. Varargs are supported via the SWIG <tt>%varargs</tt> - directive. This directive allows you to specify a (finite) - argument list which will be inserted into the wrapper in place - of the variable length argument indicator. As an example, - consider the function <tt>printf()</tt>. Its declaration would - appear as follows: - </p> - - <p> - See the following section - on <a href="Varargs.html#Varargs">Variable Length arguments</a> - provides examples on how <tt>%varargs</tt> can be used, along - with other ways such functions can be wrapped. - </p> - -<H3><a name="Allegrocl_nn33">20.3.12 C++ Exceptions</a></H3> - - - <p> - Each C++ wrapper includes a handler to catch any exceptions that may - be thrown while in foreign code. This helps prevent simple C++ errors - from killing the entire lisp process. There is currently no mechanism - to have these exceptions forwarded to the lisp condition system, nor - has any explicit support of the exception related SWIG typemaps been - implemented. - </p> - -<H3><a name="Allegrocl_nn34">20.3.13 Pass by value, pass by reference</a></H3> - - - <p> - Allegro CL does not support the passing of non-primitive foreign - structures by value. As a result, SWIG must automatically detect - and convert function parameters and return values to pointers - whenever necessary. This is done via the use of <tt>typemaps</tt>, - and should not require any fine tuning by the user, even for - newly defined types. - </p> - -<H2><a name="Allegrocl_nn35">20.4 Typemaps</a></H2> - - -<p> - SWIG Typemaps provide a powerful tool for automatically generating - code to handle various menial tasks required of writing an interface - to foreign code. The purpose of this section is to describe each of - the typemaps used by the Allegro CL module. Please read the chapter - on <a href="Typemaps.html#Typemaps">Typemaps</a> for more information. -</p> - -<H3><a name="Allegrocl_nn36">20.4.1 Code Generation in the C++ Wrapper</a></H3> - - - - <p> - Every C++ wrapper generated by SWIG takes the following form: - </p> - - <div class="diagram"> - <pre> -return-val wrapper-name(parm0, parm1, ..., parmN) -{ - return-val lresult; /* return value from wrapper */ - <local-declaration> - ... results; /* return value from function call */ - - <binding locals to parameters> - - try { - result = function-name(local0, local1, ..., localN); - - <convert and bind result to lresult> - - return lresult; - catch (...) { - return (int)0; - } - </pre> - </div> - -<H4><a name="Allegrocl_nn37">20.4.1.1 IN Typemap</a></H4> - - - <p> - the <tt>in</tt> typemap is used to generate code to convert parameters - passed to C++ wrapper functions into the arguments desired for the - call being wrapped. That is, it fills in the code for the - <tt><binding locals to parameters></tt> section above. We - use this map to automatically convert parameters passed by - reference to the wrapper function into by-value arguments for - the wrapped call, and also to convert boolean values, which are - passed as integers from lisp (by default), into the appropriate - type for the language of code being wrapped. - </p> - - <p>These are the default specifications for the IN typemap. Here, - <tt>$input</tt> refers to the parameter code is being generated - for, and <tt>$1</tt> is the local variable to which it is - being assigned. The default settings of this typemap are as follows: - </p> - - <div class="code"> - <pre> -%typemap(in) bool "$1 = (bool)$input;"; -%typemap(in) char, unsigned char, signed char, - short, signed short, unsigned short, - int, signed int, unsigned int, - long, signed long, unsigned long, - float, double, long double, char *, void *, void, - enum SWIGTYPE, SWIGTYPE *, - SWIGTYPE[ANY], SWIGTYPE & "$1 = $input;"; -%typemap(in) SWIGTYPE "$1 = *$input;"; - </pre> - </div> - -<H4><a name="Allegrocl_nn38">20.4.1.2 OUT Typemap</a></H4> - - - <p> - The <tt>out</tt> typemap is used to generate code to form the - return value of the wrapper from the return value of the wrapped - function. This code is placed in the <convert and bind result to lresult> - section of the above code diagram. Its default mapping is as follows: - </p> - - <div class="code"> - <pre> -%typemap(out) bool "$result = (int)$1;"; -%typemap(out) char, unsigned char, signed char, - short, signed short, unsigned short, - int, signed int, unsigned int, - long, signed long, unsigned long, - float, double, long double, char *, void *, void, - enum SWIGTYPE, SWIGTYPE *, - SWIGTYPE[ANY], SWIGTYPE & "$result = $1;"; -%typemap(out) SWIGTYPE "$result = new $1_type($1);"; - </pre> - </div> - -<H4><a name="Allegrocl_nn39">20.4.1.3 CTYPE Typemap</a></H4> - - - <p> - This typemap is not used for code generation, but purely for the - transformation of types in the parameter list of the wrapper function. - Its primary use is to handle by-value to by-reference conversion in the - wrappers parameter list. Its default settings are: - </p> - - <div class="code"> - <pre> -%typemap(ctype) bool "int"; -%typemap(ctype) char, unsigned char, signed char, - short, signed short, unsigned short, - int, signed int, unsigned int, - long, signed long, unsigned long, - float, double, long double, char *, void *, void, - enum SWIGTYPE, SWIGTYPE *, - SWIGTYPE[ANY], SWIGTYPE & "$1_ltype"; -%typemap(ctype) SWIGTYPE "$&1_type"; - </pre> - </div> - - <p> - These three typemaps are specifically employed by the - Allegro CL interface generator. SWIG also implements a number of - other typemaps that can be used for generating code in the C/C++ - wrappers. You can read about - these <a href="Typemaps.html#Typemaps_nn25">common typemaps</a> here. - </p> - -<H3><a name="Allegrocl_nn40">20.4.2 Code generation in Lisp wrappers</a></H3> - - - <p> - A number of custom typemaps have also been added to facilitate - the generation of code in the lisp side of the interface. These - are described below. The basic code generation structure is - applied as a series of nested expressions, one for each - parameter, then one for manipulating the return value, and last, - the foreign function call itself. - </p> - - <p> - Note that the typemaps below use fully qualified symbols where - necessary. Users writing their own typemaps should do likewise. - See the explanation in the last paragraph of - <a href="#Allegrocl_nn15">16.3.1 Namespaces</a> for details. - </p> - -<H4><a name="Allegrocl_nn41">20.4.2.1 LIN Typemap</a></H4> - - - <p> - The LIN typemap allows for the manipulating the lisp objects - passed as arguments to the wrapping defun before passing them to - the foreign function call. For example, when passing lisp - strings to foreign code, it is often necessary to copy the - string into a foreign structure of type (:char *) of appropriate - size, and pass this copy to the foreign call. Using the LIN - typemap, one could arrange for the stack-allocation of a foreign - char array, copy your string into it, and not have to worry - about freeing the copy after the function returns. - </p> - - <p>The LIN typemap accepts the following <tt>$variable</tt> references. - </p> - <ul> - <li><tt>$in</tt> - expands to the name of the parameter being - applied to this typemap - </li> - <li><tt>$out</tt> - expands to the name of the local variable - assigned to this typemap - </li> - <li><tt>$in_fftype</tt> - the foreign function type of the C type.</li> - <li><tt>$*in_fftype</tt> - the foreign function type of the C type - with one pointer removed. If there is no pointer, then $*in_fftype - is the same as $in_fftype. - </li> - <li><tt>$body</tt> - very important. Instructs SWIG where - subsequent code generation steps should be inserted into the - current typemap. Leaving out a <tt>$body</tt> reference - will result in lisp wrappers that do very little by way of - calling into foreign code. Not recommended. - </li> - </ul> - - <div class="code"> - <pre> -%typemap(lin) SWIGTYPE "(cl:let (($out $in))\n $body)"; - </pre> - </div> - -<H4><a name="Allegrocl_nn42">20.4.2.2 LOUT Typemap</a></H4> - - - <p> - The LOUT typemap is the means by which we effect the wrapping of - foreign pointers in CLOS instances. It is applied after all LIN - typemaps, and immediately before the actual foreign-call. - </p> - - <p>The LOUT typemap uses the following $variable - </p> - <ul> - <li><tt>$lclass</tt> - Expands to the CLOS class that - represents foreign-objects of the return type matching this - typemap. - </li> - <li><tt>$body</tt> - Same as for the LIN map. Place this - variable where you want the foreign-function call to occur. - </li> - <li><tt>$ldestructor</tt> - Expands to the symbol naming the destructor for this - class ($lclass) of object. Allows you to insert finalization or automatic garbage - collection into the wrapper code (see default mappings below). - </li> - </ul> - - <div class="code"> - <pre> -%typemap(lout) bool, char, unsigned char, signed char, - short, signed short, unsigned short, - int, signed int, unsigned int, - long, signed long, unsigned long, - float, double, long double, char *, void *, void, - enum SWIGTYPE "$body"; -%typemap(lout) SWIGTYPE[ANY], SWIGTYPE *, - SWIGTYPE & "(cl:make-instance '$lclass :foreign-address $body)"; -%typemap(lout) SWIGTYPE "(cl:let* ((address $body)\n - (ACL_result (cl:make-instance '$lclass :foreign-address address)))\n - (cl:unless (cl::zerop address)\n - (excl:schedule-finalization ACL_result #'$ldestructor))\n - ACL_result)"; - </pre> - </div> - -<H4><a name="Allegrocl_nn43">20.4.2.3 FFITYPE Typemap</a></H4> - - - - <p> - The FFITYPE typemap works as a helper for a body of code that - converts C/C++ type specifications into Allegro CL foreign-type - specifications. These foreign-type specifications appear in - ff:def-foreing-type declarations, and in the argument list and - return values of ff:def-foreign-calls. You would modify this - typemap if you want to change how the FFI passes through - arguments of a given type. For example, if you know that a - particular compiler represents booleans as a single byte, you - might add an entry for: - </p> - - <div class="code"> - <pre> -%typemap(ffitype) bool ":unsigned-char"; - </pre> - </div> - - <p> - Note that this typemap is pure type transformation, and is not - used in any code generations step the way the LIN and LOUT - typemaps are. The default mappings for this typemap are: - </p> - - <div class="code"> - <pre> -%typemap(ffitype) bool ":int"; -%typemap(ffitype) char ":char"; -%typemap(ffitype) unsigned char ":unsigned-char"; -%typemap(ffitype) signed char ":char"; -%typemap(ffitype) short, signed short ":short"; -%typemap(ffitype) unsigned short ":unsigned-short"; -%typemap(ffitype) int, signed int ":int"; -%typemap(ffitype) unsigned int ":unsigned-int"; -%typemap(ffitype) long, signed long ":long"; -%typemap(ffitype) unsigned long ":unsigned-long"; -%typemap(ffitype) float ":float"; -%typemap(ffitype) double ":double"; -%typemap(ffitype) char * "(* :char)"; -%typemap(ffitype) void * "(* :void)"; -%typemap(ffitype) void ":void"; -%typemap(ffitype) enum SWIGTYPE ":int"; -%typemap(ffitype) SWIGTYPE & "(* :void)"; - </pre> - </div> - -<H4><a name="Allegrocl_nn44">20.4.2.4 LISPTYPE Typemap</a></H4> - - - <p> - This is another type only transformation map, and is used to - provide the lisp-type, which is the optional third argument in - argument specifier in a ff:def-foreign-call form. Specifying a - lisp-type allows the foreign call to perform type checking on - the arguments passed in. The default entries in this typemap are: - </p> - - <div class="code"> - <pre> -%typemap(lisptype) bool "cl:boolean"; -%typemap(lisptype) char "cl:character"; -%typemap(lisptype) unsigned char "cl:integer"; -%typemap(lisptype) signed char "cl:integer"; - </pre> - </div> - -<H4><a name="Allegrocl_nn45">20.4.2.5 LISPCLASS Typemap</a></H4> - - - <p> - The LISPCLASS typemap is used to generate the method signatures - for the generic-functions which wrap overloaded functions and - functions with defaulted arguments. The default entries are: - </p> - - <div class="code"> - <pre> -%typemap(lispclass) bool "t"; -%typemap(lispclass) char "cl:character"; -%typemap(lispclass) unsigned char, signed char, - short, signed short, unsigned short, - int, signed int, unsigned int, - long, signed long, unsigned long, - enum SWIGTYPE "cl:integer"; -%typemap(lispclass) float "cl:single-float"; -%typemap(lispclass) double "cl:double-float"; -%typemap(lispclass) char * "cl:string"; - </pre> - </div> - -<H3><a name="Allegrocl_nn46">20.4.3 Modifying SWIG behavior using typemaps</a></H3> - - - <p> - The following example shows how we made use of the above - typemaps to add support for the wchar_t type. - </p> - - <div class="code"> - <pre> -%typecheck(SWIG_TYPECHECK_UNICHAR) wchar_t { $1 = 1; }; - -%typemap(in) wchar_t "$1 = $input;"; -%typemap(lin) wchar_t "(cl:let (($out (cl:char-code $in)))\n $body)"; -%typemap(lin) wchar_t* "(excl:with-native-string - ($out $in - :external-format #+little-endian :fat-le - #-little-endian :fat)\n - $body)" - -%typemap(out) wchar_t "$result = $1;"; -%typemap(lout) wchar_t "(cl:code-char $body)"; -%typemap(lout) wchar_t* "(excl:native-to-string $body - :external-format #+little-endian :fat-le - #-little-endian :fat)"; - -%typemap(ffitype) wchar_t ":unsigned-short"; -%typemap(lisptype) wchar_t ""; -%typemap(ctype) wchar_t "wchar_t"; -%typemap(lispclass) wchar_t "cl:character"; -%typemap(lispclass) wchar_t* "cl:string"; - </pre> - </div> - -<H2><a name="Allegrocl_nn47">20.5 Identifier Converter functions</a></H2> - - -<H3><a name="Allegrocl_nn48">20.5.1 Creating symbols in the lisp environment</a></H3> - - -<p> - Various symbols must be generated in the lisp environment to which - class definitions, functions, constants, variables, etc. must be - bound. Rather than force a particular convention for naming these - symbols, an identifier (to symbol) conversion function is used. A - user-defined identifier-converter can then implement any symbol - naming, case-modifying, scheme desired. -</p> - -<p> - In generated SWIG code, whenever some interface object must be - referenced by its lisp symbol, a macro is inserted that calls the - identifier-converter function to generate the appropriate symbol - reference. It is therefore expected that the identifier-converter - function reliably return the same (eq) symbol given the same set - of arguments. -</p> - -<H3><a name="Allegrocl_nn49">20.5.2 Existing identifier-converter functions</a></H3> - - - <p>Two basic identifier routines have been defined. -<H4><a name="Allegrocl_nn50">20.5.2.1 identifier-convert-null</a></H4> - - - <p> - No modification of the identifier string is performed. Based on - other arguments, the identifier may be concatenated with other - strings, from which a symbol will be created. - </p> - -<H4><a name="Allegrocl_nn51">20.5.2.2 identifier-convert-lispify</a></H4> - - - <p> - All underscores in the identifier string are converted to - hyphens. Otherwise, identifier-convert-lispify performs the - same symbol transformations. - </p> - -<H4><a name="Allegrocl_nn52">20.5.2.3 Default identifier to symbol conversions</a></H4> - - - <p> - Check the definitions of the above two default - identifier-converters in <tt>Lib/allegrocl/allegrocl.swg</tt> for - default naming conventions. - </p> - -<H3><a name="Allegrocl_nn53">20.5.3 Defining your own identifier-converter</a></H3> - - -<p> - A user-defined identifier-converter function should conform to the following - specification: -</p> - -<div class="targetlang"> -<pre> -(defun identifier-convert-fn (id &key type class arity) ...body...) -result ==> symbol or (setf symbol) -</pre> -</div> - -<p>The <tt>ID</tt> argument is a string representing an identifier in the -foreign environment. -</p> - -<p> -The :type keyword argument provides more information on the type of -identifier. Its value is a symbol. This allows the -identifier-converter to apply different heuristics when mapping -different types of identifiers to symbols. SWIG will generate calls -to your identifier-converter using the following types. -</p> - -<ul> - <li>:class - names a CLOS class.</li> - <li>:constant - names a defconstant</li> - <li>:constructor - names a function for creating a foreign object</li> - <li>:destructor - names a function for freeing a foreign object</li> - <li>:function - names a CLOS wrapping defmethod or defun.</li> - <li>:ff-operator - names a foreign call defined via ff:def-foreign-call</li> - <li>:getter - getter function</li> - <li>:namespace - names a C++ namespace</li> - <li>:setter - names a setter function. May return a (setf symbol) reference</li> - <li>:operator - names a C++ operator, such as Operator=, Operator*.</li> - <li>:slot - names a slot in a struct/class/union declaration.</li> - <li>:type - names a foreign-type defined via ff:def-foreign-type.</li> - <li>:variable - names a variable defined via ff:def-foreign-variable.</li> -</ul> - -<p> -The :class keyword argument is a string naming a foreign -class. When non-nil, it indicates that the current identifier has -scope in the specified class. -</p> - -<p> -The :arity keyword argument only appears in swig:swig-defmethod forms -generated for overloaded functions. Its value is an integer -indicating the number of arguments passed to the routine indicated by -this identifier. -</p> - -<H3><a name="Allegrocl_nn54">20.5.4 Instructing SWIG to use a particular identifier-converter</a></H3> - - -<p> - By default, SWIG will use identifier-converter-null. To specify - another convert function, use the <tt>-identifier-converter</tt> - command-line argument. The value should be a string naming the - function you wish the interface to use instead, when generating - symbols. ex: -</p> - -<div class="code"> -<pre> -% swig -allegrocl -c++ -module mymodule -identifier-converter my-identifier-converter -</pre> -</div> - - -</body> -</html> diff --git a/Doc/Manual/Chicken.html b/Doc/Manual/Chicken.html deleted file mode 100644 index 3a80811bd..000000000 --- a/Doc/Manual/Chicken.html +++ /dev/null @@ -1,597 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> -<html> -<head> -<title>SWIG and Chicken</title> -<link rel="stylesheet" type="text/css" href="style.css"> -<meta http-equiv="content-type" content="text/html; charset=UTF-8"> -</head> - -<body bgcolor="#ffffff"> - -<H1><a name="Chicken">23 SWIG and Chicken</a></H1> -<!-- INDEX --> -<div class="sectiontoc"> -<ul> -<li><a href="#Chicken_nn2">Preliminaries</a> -<ul> -<li><a href="#Chicken_nn3">Running SWIG in C mode</a> -<li><a href="#Chicken_nn4">Running SWIG in C++ mode</a> -</ul> -<li><a href="#Chicken_nn5">Code Generation</a> -<ul> -<li><a href="#Chicken_nn6">Naming Conventions</a> -<li><a href="#Chicken_nn7">Modules</a> -<li><a href="#Chicken_nn8">Constants and Variables</a> -<li><a href="#Chicken_nn9">Functions</a> -<li><a href="#Chicken_nn10">Exceptions</a> -</ul> -<li><a href="#Chicken_nn11">TinyCLOS</a> -<li><a href="#Chicken_nn12">Linkage</a> -<ul> -<li><a href="#Chicken_nn13">Static binary or shared library linked at compile time</a> -<li><a href="#Chicken_nn14">Building chicken extension libraries</a> -<li><a href="#Chicken_nn15">Linking multiple SWIG modules with TinyCLOS</a> -</ul> -<li><a href="#Chicken_nn16">Typemaps</a> -<li><a href="#Chicken_nn17">Pointers</a> -<ul> -<li><a href="#Chicken_collection">Garbage collection</a> -</ul> -<li><a href="#Chicken_nn18">Unsupported features and known problems</a> -<ul> -<li><a href="#Chicken_nn19">TinyCLOS problems with Chicken version <= 1.92</a> -</ul> -</ul> -</div> -<!-- INDEX --> - - - - <p> - This chapter describes SWIG's support of CHICKEN. CHICKEN is a - Scheme-to-C compiler supporting most of the language features as - defined in the <i>Revised^5 Report on Scheme</i>. Its main - attributes are that it - </p> - - <ol> - <li>generates portable C code</li> - <li>includes a customizable interpreter</li> - <li>links to C libraries with a simple Foreign Function Interface</li> - <li>supports full tail-recursion and first-class continuations</li> - </ol> - - <p> - When confronted with a large C library, CHICKEN users can use - SWIG to generate CHICKEN wrappers for the C library. However, - the real advantages of using SWIG with CHICKEN are its - <strong>support for C++</strong> -- object-oriented code is - difficult to wrap by hand in CHICKEN -- and its <strong>typed - pointer representation</strong>, essential for C and C++ - libraries involving structures or classes. - - </p> - -<H2><a name="Chicken_nn2">23.1 Preliminaries</a></H2> - - - <p> - 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 - <strong>greater than or equal to 1.89</strong>. - To use a chicken version between 1.40 and 1.89, see the <a href="#Chicken_collection">Garbage collection</a> - section below. - </p> - - <p> - You may want to look at any of the examples in Examples/chicken/ - directory for the basic steps to run SWIG CHICKEN. - </p> - -<H3><a name="Chicken_nn3">23.1.1 Running SWIG in C mode</a></H3> - - - <p> - To run SWIG CHICKEN in C mode, use - the -chicken option. - </p> - - <div class="shell"> - <pre>% swig -chicken example.i</pre> - </div> - - <p> - To allow the wrapper to take advantage of future CHICKEN code - generation improvements, part of the wrapper is direct CHICKEN - function calls (<tt>example_wrap.c</tt>) and part is CHICKEN - Scheme (<tt>example.scm</tt>). The basic Scheme code must - be compiled to C using your system's CHICKEN compiler or - both files can be compiled directly using the much simpler <tt>csc</tt>. - </p> - - <div class="shell"> -<pre> -% chicken example.scm -output-file oexample.c -</pre> - </div> - - <p> - So for the C mode of SWIG CHICKEN, <tt>example_wrap.c</tt> and - <tt>oexample.c</tt> are the files that must be compiled to - object files and linked into your project. - </p> - -<H3><a name="Chicken_nn4">23.1.2 Running SWIG in C++ mode</a></H3> - - - <p> - To run SWIG CHICKEN in C++ mode, use - the -chicken -c++ option. - </p> - - <div class="shell"> - <pre>% swig -chicken -c++ example.i</pre> - </div> - - <p> - This will generate <tt>example_wrap.cxx</tt> and - <tt>example.scm</tt>. The basic Scheme code must be - compiled to C using your system's CHICKEN compiler or - both files can be compiled directly using the much simpler <tt>csc</tt>. - </p> - - <div class="shell"> - <pre>% chicken example.scm -output-file oexample.c</pre> - </div> - - <p> - So for the C++ mode of SWIG CHICKEN, <tt>example_wrap.cxx</tt> - and <tt>oexample.c</tt> are the files that must be compiled to - object files and linked into your project. - </p> - -<H2><a name="Chicken_nn5">23.2 Code Generation</a></H2> - - -<H3><a name="Chicken_nn6">23.2.1 Naming Conventions</a></H3> - - - <p> - Given a C variable, function or constant declaration named - <tt>Foo_Bar</tt>, the declaration will be available - in CHICKEN as an identifier ending with - <tt>Foo-Bar</tt>. That is, an underscore is converted - to a dash. - </p> - - <p> - You may control what the CHICKEN identifier will be by using the - <tt>%rename</tt> SWIG directive in the SWIG interface file. - </p> - -<H3><a name="Chicken_nn7">23.2.2 Modules</a></H3> - - - <p> - The name of the module must be declared one of two ways: - <ul> - <li>Placing <tt>%module example</tt> in the SWIG interface - file.</li> - <li>Using <tt>-module example</tt> on the SWIG command - line.</li> - </ul> - - <p> - The generated example.scm file then exports <code>(declare (unit modulename))</code>. - If you do not want SWIG to export the <code>(declare (unit modulename))</code>, pass - the -nounit option to SWIG. - - <p> - CHICKEN will be able to access the module using the <code>(declare - (uses <i>modulename</i>))</code> CHICKEN Scheme form. - </p> - -<H3><a name="Chicken_nn8">23.2.3 Constants and Variables</a></H3> - - - <p> - Constants may be created using any of the four constructs in - the interface file: - </p> - <ol> - <li><code>#define MYCONSTANT1 ...</code></li> - <li><code>%constant int MYCONSTANT2 = ...</code></li> - <li><code>const int MYCONSTANT3 = ...</code></li> - <li><code>enum { MYCONSTANT4 = ... };</code></li> - </ol> - - <p> - In all cases, the constants may be accessed from within CHICKEN - using the form <tt>(MYCONSTANT1)</tt>; that is, the constants - may be accessed using the read-only parameter form. - </p> - - <p> - Variables are accessed using the full parameter form. - For example, to set the C variable "int my_variable;", use the - Scheme form <tt>(my-variable 2345)</tt>. To get the C variable, - use <tt>(my-variable)</tt>. - </p> - - <p> - The <tt>%feature("constasvar")</tt> can be applied to any constant - or immutable variable. Instead of exporting the constant as - a function that must be called, the constant will appear as a - scheme variable. This causes the generated .scm file to just contain the code - <tt>(set! MYCONSTANT1 (MYCONSTANT1))</tt>. See - <a href="Customization.html#Customization_features">Features and the %feature directive</a> - for info on how to apply the %feature. - </p> - -<H3><a name="Chicken_nn9">23.2.4 Functions</a></H3> - - - <p> - C functions declared in the SWIG interface file will have - corresponding CHICKEN Scheme procedures. For example, the C - function "int sqrt(double x);" will be available using the - Scheme form <tt>(sqrt 2345.0)</tt>. A <code>void</code> return - value will give C_SCHEME_UNDEFINED as a result. - </p> - <p> - A function may return more than one value by using the - <code>OUTPUT</code> specifier (see Lib/chicken/typemaps.i). - They will be returned as multiple values using <code>(values)</code> if there is more than one - result (that is, a non-void return value and at least one argout - parameter, or a void return value and at least two argout - parameters). The return values can then be accessed with <code>(call-with-values)</code>. - </p> - -<H3><a name="Chicken_nn10">23.2.5 Exceptions</a></H3> - - - <p>The SWIG chicken module has support for exceptions thrown from - C or C++ code to be caught in scheme. - See <a href="Customization.html#Customization_exception">Exception handling with %exception</a> - for more information about declaring exceptions in the interface file. - </p> - - <p>Chicken supports both the <code>SWIG_exception(int code, const char *msg)</code> interface - as well as a <code>SWIG_ThrowException(C_word val)</code> function for throwing exceptions from - inside the %exception blocks. <code>SWIG_exception</code> will throw a list consisting of the code - (as an integer) and the message. Both of these will throw an exception using <code>(abort)</code>, - which can be handled by <code>(handle-exceptions)</code>. See - the Chicken manual on Exceptions - and <a href="http://srfi.schemers.org/srfi-12/srfi-12.html">SFRI-12</a>. Since the exception values are thrown - directly, if <code>(condition-case)</code> is used to catch an exception the exception will come through in the <code>val ()</code> case. - </p> - - <p>The following simple module</p> - -<div class="code"><pre> -%module exception_test - -%inline %{ - void test_throw(int i) throws (int) { - if (i == 1) throw 15; - } -%} -</pre></div> - - <p>could be run with</p> - -<div class="targetlang"><pre> -(handle-exceptions exvar - (if (= exvar 15) - (print "Correct!") - (print "Threw something else " exvar)) - (test-throw 1)) -</pre></div> - - -<H2><a name="Chicken_nn11">23.3 TinyCLOS</a></H2> - - - <p> - The author of TinyCLOS, Gregor Kiczales, describes TinyCLOS as: - "Tiny CLOS is a Scheme implementation of a 'kernelized' CLOS, with a - metaobject protocol. The implementation is even simpler than - the simple CLOS found in 'The Art of the Metaobject Protocol', - weighing in at around 850 lines of code, including (some) - comments and documentation." - </p> - - <p> - Almost all good Scheme books describe how to use metaobjects and - generic procedures to implement an object-oriented Scheme - system. Please consult a Scheme book if you are unfamiliar - with the concept. - </p> - - <p> - - CHICKEN has a modified version of TinyCLOS, which SWIG CHICKEN - uses if the -proxy argument is given. If -proxy is passed, then - the generated example.scm file will contain TinyCLOS class definitions. - A class named Foo is declared as <Foo>, and each member variable - is allocated a slot. Member functions are exported as generic functions. - - <p> - - Primitive symbols and functions (the interface that would be presented if - -proxy was not passed) are hidden and no longer accessible. If the -unhideprimitive - command line argument is passed to SWIG, then the primitive symbols will be - available, but each will be prefixed by the string "primitive:" - - <p> - - The exported symbol names can be controlled with the -closprefix and -useclassprefix arguments. - If -useclassprefix is passed to SWIG, every member function will be generated with the class name - as a prefix. If the -closprefix mymod: argument is passed to SWIG, then the exported functions will - be prefixed by the string "mymod:". If -useclassprefix is passed, -closprefix is ignored. - - </p> - -<H2><a name="Chicken_nn12">23.4 Linkage</a></H2> - - - <p> - Please refer to <em>CHICKEN - A practical and portable Scheme - system - User's manual</em> for detailed help on how to link - object files to create a CHICKEN Scheme program. Briefly, to - link object files, be sure to add <tt>`chicken-config - -extra-libs -libs`</tt> or <tt>`chicken-config -shared - -extra-libs -libs`</tt>to your linker options. Use the - <tt>-shared</tt> option if you want to create a dynamically - loadable module. You might also want to use the much simpler - <tt>csc</tt> or <tt>csc.bat</tt>. - </p> - - <p>Each scheme file that is generated - by SWIG contains <code>(declare (uses <i>modname</i>))</code>. This means that to load the - module from scheme code, the code must include <code>(declare (uses <i>modname</i>))</code>. - </p> - - -<H3><a name="Chicken_nn13">23.4.1 Static binary or shared library linked at compile time</a></H3> - - - <p>We can easily use csc to build a static binary.</p> - -<div class="shell"> -<pre> -$ swig -chicken example.i -$ csc -v example.scm example_impl.c example_wrap.c test_script.scm -o example -$ ./example -</pre> -</div> - -<p>Similar to the above, any number of <tt>module.scm</tt> files could be compiled -into a shared library, and then that shared library linked when compiling the -main application.</p> - -<div class="shell"> -<pre> -$ swig -chicken example.i -$ csc -sv example.scm example_wrap.c example_impl.c -o example.so -</pre> -</div> - -<p>The <tt>example.so</tt> file can then linked with <tt>test_script.scm</tt> when it -is compiled, in which case <tt>test_script.scm</tt> must have <code>(declare (uses example))</code>. -Multiple SWIG modules could have been linked into <tt>example.so</tt> and each -one accessed with a <code>(declare (uses ... ))</code>. -</p> - -<div class="shell"> -<pre> -$ csc -v test_script.scm -lexample -</pre> -</div> - -<p>An alternative is that the test_script.scm can have the code <code>(load-library 'example "example.so")</code>, -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 <tt>csi</tt>. -</p> - -<H3><a name="Chicken_nn14">23.4.2 Building chicken extension libraries</a></H3> - - -<p>Building a shared library like in the above section only works if the library -is linked at compile time with a script containing <code>(declare (uses ...))</code> or is -loaded explicitly with <code>(load-library 'example "example.so")</code>. It is -not the format that CHICKEN expects for extension libraries and eggs. The problem is the -<code>(declare (unit <i>modname</i>))</code> inside the <tt>modname.scm</tt> file. There are -two possible solutions to this.</p> - -<p>First, SWIG accepts a <tt>-nounit</tt> argument, in which case the <code>(declare (unit <i>modname</i>))</code> -is not generated. Then, the <tt>modname.scm</tt> and <tt>modname_wrap.c</tt> files <b>must</b> be compiled into -their own shared library.</p> - -<div class="shell"> -<pre> -$ csc -sv modname.scm modname_wrap.c modname_impl.c -o modname.so -</pre> -</div> - -<p>This library can then be loaded by scheme code with the <code>(require 'modname)</code> function. -See the -Loading-extension-libraries in the eval unit inside the CHICKEN manual for more information.</p> - -<p>Another alternative is to run SWIG normally and create a scheme file that contains <code>(declare (uses <i>modname</i>))</code> -and then compile that file into the shared library as well. For example, inside the <tt>mod_load.scm</tt> file,</p> - -<div class="targetlang"> -<pre> -(declare (uses mod1)) -(declare (uses mod2)) -</pre> -</div> - -<p>Which would then be compiled with</p> - -<div class="shell"> -<pre> -$ 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 -</pre> -</div> - -<p>Then the extension library can be loaded with <code>(require 'mod)</code>. As we can see here, -<tt>mod_load.scm</tt> contains the code that gets executed 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 -<code>%import</code></p> - -<p>In either method, the files that are compiled into the shared library could also be -packaged into an egg. The <tt>mod1_wrap.c</tt> and <tt>mod2_wrap.c</tt> 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.</p> - -<p>See the <tt>Examples/chicken/egg</tt> directory in the SWIG source for an example that builds -two eggs, one using the first method and one using the second method.</p> - -<H3><a name="Chicken_nn15">23.4.3 Linking multiple SWIG modules with TinyCLOS</a></H3> - - -<p>Linking together multiple modules that share type information using the <code>%import</code> -directive while also using <tt>-proxy</tt> is more complicated. For example, if <tt>mod2.i</tt> imports <tt>mod1.i</tt>, then the -<tt>mod2.scm</tt> file contains references to symbols declared in <tt>mod1.scm</tt>, -and thus a <code>(declare (uses <i>mod1</i>))</code> or <code>(require '<i>mod1</i>)</code> must be exported -to the top of <tt>mod2.scm</tt>. By default, when SWIG encounters an <code>%import "modname.i"</code> directive, -it exports <code>(declare (uses <i>modname</i>))</code> into the scm file. This works fine unless mod1 was compiled with -the <tt>-nounit</tt> argument or was compiled into an extension library with other modules under a different name.</p> - -<p>One option is to override the automatic generation of <code>(declare (uses mod1))</code> -by passing the <tt>-noclosuses</tt> option to SWIG when compiling <tt>mod2.i</tt>. -SWIG then provides the <code>%insert(closprefix) %{ %}</code> directive. Any scheme code inside that directive is inserted into the -generated .scm file, and if <tt>mod1</tt> was compiled with <tt>-nounit</tt>, the directive should contain <code>(require 'mod1)</code>. -This option allows for mixed loading as well, where some modules are imported with <code>(declare (uses <i>modname</i>))</code> -(which means they were compiled without -nounit) and some are imported with <code>(require 'modname)</code>.</p> - -<p>The other option is to use the second idea in the above section. Compile all the modules normally, without any -<code>%insert(closprefix)</code>, <tt>-nounit</tt>, or <tt>-noclosuses</tt>. Then the modules will import each other correctly -with <code>(declare (uses ...))</code>. -To create an extension library or an egg, just create a <tt>module_load.scm</tt> file that <code>(declare (uses ...))</code> -all the modules.</p> - -<H2><a name="Chicken_nn16">23.5 Typemaps</a></H2> - - - <p> - The Chicken module handles all types via typemaps. This information is - read from <code>Lib/chicken/typemaps.i</code> and - <code>Lib/chicken/chicken.swg</code>. - </p> - -<H2><a name="Chicken_nn17">23.6 Pointers</a></H2> - - - <p> - For pointer types, SWIG uses CHICKEN tagged pointers. - - A tagged pointer is an ordinary CHICKEN pointer with an - extra slot for a void *. With SWIG - CHICKEN, this void * is a pointer to a type-info - structure. So each pointer used as input or output from - the SWIG-generated CHICKEN wrappers will have type - information attached to it. This will let the wrappers - correctly determine which method should be called - according to the object type hierarchy exposed in the SWIG - interface files. - </p> - <p> - To construct a Scheme object from a C pointer, the wrapper code - calls the function - <code>SWIG_NewPointerObj(void *ptr, swig_type_info *type, int owner)</code>, - The function that calls <code>SWIG_NewPointerObj</code> must have a variable declared - <code>C_word *known_space = C_alloc(C_SIZEOF_SWIG_POINTER);</code> - It is ok to call <code>SWIG_NewPointerObj</code> more than once, - just make sure known_space has enough space for all the created pointers. - </p> - <p> - To get the pointer represented by a CHICKEN tagged pointer, the - wrapper code calls the function - <code>SWIG_ConvertPtr(C_word s, void **result, swig_type_info *type, int flags)</code>, - passing a pointer to a struct representing the expected pointer - type. flags is either zero or SWIG_POINTER_DISOWN (see below). - </p> - -<H3><a name="Chicken_collection">23.6.1 Garbage collection</a></H3> - - - <p>If the owner flag passed to <code>SWIG_NewPointerObj</code> is 1, <code>NewPointerObj</code> will add a - finalizer to the type which will call the destructor or delete method of - that type. The destructor and delete functions are no longer exported for - use in scheme code, instead SWIG and chicken manage pointers. - In situations where SWIG knows that a function is returning a type that should - be garbage collected, SWIG will automatically set the owner flag to 1. For other functions, - the <code>%newobject</code> directive must be specified for functions whose return values - should be garbage collected. See - <a href="Customization.html#Customization_ownership">Object ownership and %newobject</a> for more information. - </p> - - <p>In situations where a C or C++ function will assume ownership of a pointer, and thus - chicken should no longer garbage collect it, SWIG provides the <code>DISOWN</code> input typemap. - After applying this typemap (see the <a href="Typemaps.html#Typemaps">Typemaps chapter</a> for more information on how to apply typemaps), - any pointer that gets passed in will no longer be garbage collected. - An object is disowned by passing the <code>SWIG_POINTER_DISOWN</code> flag to <code>SWIG_ConvertPtr</code>. - <b>Warning:</b> Since the lifetime of the object is now controlled by the underlying code, the object might - get deleted while the scheme code still holds a pointer to it. Further use of this pointer - can lead to a crash. - </p> - - <p>Adding a finalizer function from C code was added to chicken in the 1.89 release, so garbage collection - does not work for chicken versions below 1.89. If you would like the SWIG generated code to work with - chicken 1.40 to 1.89, pass the <code>-nocollection</code> argument to SWIG. This will not export code - inside the _wrap.c file to register finalizers, and will then export destructor functions which - must be called manually. - </p> - -<H2><a name="Chicken_nn18">23.7 Unsupported features and known problems</a></H2> - - - <ul> - <li>No director support.</li> - <li>No support for c++ standard types like std::vector.</li> - <li>The TinyCLOS wrappers for overloaded functions will not work correctly when using - <a href="SWIGPlus.html#SWIGPlus_default_args">%feature(compactdefaultargs)</a>.</li> - </ul> - -<H3><a name="Chicken_nn19">23.7.1 TinyCLOS problems with Chicken version <= 1.92</a></H3> - - - <p>In Chicken versions equal to or below 1.92, TinyCLOS has a limitation such that generic methods do not properly work on methods - with different number of specializers: TinyCLOS assumes that every method added to a generic function - will have the same number of specializers. SWIG generates functions with different lengths of specializers - when C/C++ functions are overloaded. For example, the code</p> - -<div class="code"> -<pre> -class Foo {}; -int foo(int a, Foo *b); -int foo(int a); -</pre></div> - -<p>will produce scheme code</p> - -<div class="targetlang"> -<pre> -(define-method (foo (arg0 <top>) (arg1 <Foo>)) (<i>call primitive function</i>)) -(define-method (foo (arg0 <top>)) (<i>call primitive function</i>)) -</pre></div> - -<p>Using unpatched TinyCLOS, the second <code>(define-method)</code> will replace the first one, -so calling <code>(foo 3 f)</code> will produce an error.</p> - -<p>There are three solutions to this. The easist is to upgrade to the latest Chicken version. Otherwise, the -file <tt>Lib/chicken/tinyclos-multi-generic.patch</tt> in the SWIG source contains a patch against -tinyclos.scm inside the 1.92 chicken source to add support into TinyCLOS for multi-argument generics. (This patch was accepted into Chicken) -This requires chicken to be rebuilt and custom install of chicken. An alternative is the <tt>Lib/chicken/multi-generic.scm</tt> -file in the SWIG source. This file can be loaded after TinyCLOS is loaded, and it will override some functions -inside TinyCLOS to correctly support multi-argument generics. Please see the comments at the top of both files for more information.</p> - - </body> -</html> diff --git a/Doc/Manual/Contents.html b/Doc/Manual/Contents.html index 0370d4724..47b41186e 100644 --- a/Doc/Manual/Contents.html +++ b/Doc/Manual/Contents.html @@ -96,6 +96,7 @@ <li><a href="Windows.html#Windows_swig_exe">Building swig.exe on Windows</a> <ul> <li><a href="Windows.html#Windows_cmake">Building swig.exe using CMake</a> +<li><a href="Windows.html#Windows_mingw_msys">Building swig.exe using MSYS2</a> <li><a href="Windows.html#Windows_mingw_msys">Building swig.exe using MinGW and MSYS</a> <li><a href="Windows.html#Windows_cygwin">Building swig.exe using Cygwin</a> </ul> diff --git a/Doc/Manual/Doxygen.html b/Doc/Manual/Doxygen.html index 53238c24d..e7fd4c359 100644 --- a/Doc/Manual/Doxygen.html +++ b/Doc/Manual/Doxygen.html @@ -1354,7 +1354,7 @@ Here is the list of all Doxygen tags and the description of how they are transla </tr> <tr> <td>\throws</td> -<td>replaced wih ':raises:'</td> +<td>replaced with ':raises:'</td> </tr> <tr> <td>\todo</td> diff --git a/Doc/Manual/Extending.html b/Doc/Manual/Extending.html index 7c2a6c66c..5749f37ce 100644 --- a/Doc/Manual/Extending.html +++ b/Doc/Manual/Extending.html @@ -3613,7 +3613,7 @@ A target language is given the 'Supported' status when Examples must be available and run successfully. </li> <li> - The examples and test-suite must be fully functioning on the Travis Continuous Integration platform. + The examples and test-suite must be fully functioning on the Github Actions Continuous Integration platform. </li> </ul> @@ -3660,9 +3660,9 @@ Some minimum requirements and notes about languages with the 'Experimental' stat The number of tests in these lists should be no greater than half of the number of tests in the full test-suite. </li> <li> - The examples and test-suite must also be fully functioning on the Travis Continuous Integration platform. - However, experimental languages will be set as 'allow_failures'. - This means that pull requests and normal development commits will not break the entire Travis build should an experimental language fail. + The examples and test-suite must also be fully functioning on the Github Actions Continuous Integration platform. + However, experimental languages will be flagged as 'continue-on-error'. + This means that pull requests and normal development commits will not break the entire Github Actions build should an experimental language fail. </li> <li> Any new failed tests will be fixed on a 'best effort' basis by core developers with no promises made. diff --git a/Doc/Manual/Go.html b/Doc/Manual/Go.html index 1a5bb08c7..4e230c78b 100644 --- a/Doc/Manual/Go.html +++ b/Doc/Manual/Go.html @@ -71,6 +71,7 @@ code. SWIG fills this gap. There are (at least) two different Go compilers. The first is the gc compiler of the <a href="https://golang.org/doc/install">Go distribution</a>, normally invoked via the <a href="https://golang.org/cmd/go/">go tool</a>. +SWIG supports the gc compiler version 1.2 or later. The second Go compiler is the <a href="https://golang.org/doc/install/gccgo"> gccgo compiler</a>, which is a frontend to the GCC compiler suite. The interface to C/C++ code is completely different for the two Go compilers. @@ -142,44 +143,6 @@ You will now have a Go package that you can import from other Go packages as usual. </p> -<p> -SWIG can be used without cgo, via the <tt>-no-cgo</tt> option, but -more steps are required. This only works with Go versions before 1.5. -When using Go version 1.2 or later, or when using gccgo, the code -generated by SWIG can be linked directly into the Go program. A -typical command sequence when using the Go compiler of the Go -distribution would look like this: -</p> - -<div class="code"><pre> -% swig -go -no-cgo example.i -% gcc -c code.c # The C library being wrapped. -% gcc -c example_wrap.c -% go tool 6g example.go -% go tool 6c example_gc.c -% go tool pack grc example.a example.6 example_gc.6 code.o example_wrap.o -% go tool 6g main.go -% go tool 6l main.6 -</pre></div> - -<p> -You can also put the wrapped code into a shared library, and when using the Go -versions before 1.2 this is the only supported option. A typical command -sequence for this approach would look like this: -</p> - -<div class="code"><pre> -% swig -go -no-cgo -use-shlib example.i -% gcc -c -fpic example.c -% gcc -c -fpic example_wrap.c -% gcc -shared example.o example_wrap.o -o example.so -% go tool 6g example.go -% go tool 6c example_gc.c -% go tool pack grc example.a example.6 example_gc.6 -% go tool 6g main.go # your code, not generated by SWIG -% go tool 6l main.6 -</pre></div> - <H3><a name="Go_commandline">25.3.1 Go-specific Commandline Options</a></H3> @@ -206,9 +169,7 @@ swig -go -help <tr> <td>-no-cgo</td> -<td>Generate files that can be used directly, rather than via the Go - cgo tool. This option does not work with Go 1.5 or later. It is - required for versions of Go before 1.2.</td> +<td>This option is no longer supported.</td> </tr> <tr> @@ -279,13 +240,10 @@ swig -go -help <H3><a name="Go_outputs">25.3.2 Generated Wrapper Files</a></H3> -<p>There are two different approaches to generating wrapper files, - controlled by SWIG's <tt>-no-cgo</tt> option. The <tt>-no-cgo</tt> - option only works with version of Go before 1.5. It is required - when using versions of Go before 1.2.</p> - -<p>With or without the <tt>-no-cgo</tt> option, SWIG will generate the - following files when generating wrapper code:</p> +<p> +SWIG will generate the following files when generating wrapper +code: +</p> <ul> <li> @@ -308,17 +266,6 @@ or C++ compiler. </li> </ul> -<p>When the <tt>-no-cgo</tt> option is used, and the <tt>-gccgo</tt> - option is not used, SWIG will also generate an additional file:</p> - -<ul> -<li> -MODULE_gc.c will contain C code which should be compiled with the C -compiler distributed as part of the gc compiler. It should then be -combined with the compiled MODULE.go using go tool pack. -</li> -</ul> - <H2><a name="Go_basic_tour">25.4 A tour of basic C/C++ wrapping</a></H2> diff --git a/Doc/Manual/Guile.html b/Doc/Manual/Guile.html index 9d55b632b..26679dc4b 100644 --- a/Doc/Manual/Guile.html +++ b/Doc/Manual/Guile.html @@ -183,7 +183,7 @@ information by including a directive like this in the interface file: </div> <p> -(The <code>%scheme</code> directive allows to insert arbitrary Scheme +(The <code>%scheme</code> directive allows inserting arbitrary Scheme code into the generated file <code><var>module.scm</var></code>; it is placed between the <code>define-module</code> form and the <code>export</code> form.) diff --git a/Doc/Manual/Java.html b/Doc/Manual/Java.html index dc403a98c..2591b27b5 100644 --- a/Doc/Manual/Java.html +++ b/Doc/Manual/Java.html @@ -9095,7 +9095,7 @@ This method normally calls the C++ destructor or <tt>free()</tt> for C code. <p> The generated code can be debugged using both a Java debugger and a C++ debugger using the usual debugging techniques. Breakpoints can be set in either Java or C++ code and so both can be debugged simultaneously. -Most debuggers do not understand both Java and C++, with one noteable exception of Sun Studio, +Most debuggers do not understand both Java and C++, with one notable exception of Sun Studio, where it is possible to step from Java code into a JNI method within one environment. </p> diff --git a/Doc/Manual/Javascript.html b/Doc/Manual/Javascript.html index cce5b5e2e..54bd68521 100644 --- a/Doc/Manual/Javascript.html +++ b/Doc/Manual/Javascript.html @@ -89,19 +89,24 @@ $ swig -javascript -jsc example.i</pre> <pre> $ swig -c++ -javascript -jsc example.i</pre> </div> -<p>The V8 code that SWIG generates should work with most versions from 3.11.10 up to 3.29.14 and later.</p> -<p>The API headers for V8 >= 4.3.0 define constants which SWIG can use to -determine the V8 version it is compiling for. For versions < 4.3.0, you +<p>The V8 code that SWIG generates should work with most versions from 3.11.10. +However, the only early version that receives some testing is 3.14.5, which is +still shipped with Ubuntu for some reason. Other than that it's probably safer +to assume that versions earlier than 5.0 are no longer supported. Keep in mind +that these are V8 versions, not Node.js. To give some perspective, Node.js v6.0 +uses V8 5.0, v12.0 - 7.4, v14.0 - 8.1...</p> +<p>The API headers for V8 >= 4.3.10 define constants which SWIG can use to +determine the V8 version it is compiling for. For versions < 4.3.10, you need to specify the V8 version when running SWIG. This is specified as a hex constant, but the constant is read as pairs of decimal digits, so for V8 3.25.30 use constant 0x032530. This scheme can't represent components > 99, -but this constant is only useful for V8 < 4.3.0, and no V8 versions from +but this constant is only useful for V8 < 4.3.10, and no V8 versions from that era had a component > 99. For example:</p> <div class="shell"> <pre> $ swig -c++ -javascript -v8 -DV8_VERSION=0x032530 example.i</pre> </div> -<p>If you're targeting V8 >= 4.3.0, you would just run swig like so:</p> +<p>If you're targeting V8 >= 4.3.10, you would just run swig like so:</p> <div class="shell"> <pre> $ swig -c++ -javascript -v8 example.i</pre> @@ -401,7 +406,7 @@ the main window.</p> <p> As known from <code>node.js</code> one can use <code>require</code> to load javascript modules. -Additionally, <code>node-webkit</code> provides an API that allows to manipulate the window's menu, +Additionally, <code>node-webkit</code> provides an API that allows manipulating the window's menu, open new windows, and many more things. </p> diff --git a/Doc/Manual/Modula3.html b/Doc/Manual/Modula3.html deleted file mode 100644 index fc4ffa03c..000000000 --- a/Doc/Manual/Modula3.html +++ /dev/null @@ -1,942 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> -<html> -<head> -<title>SWIG and Modula-3</title> -<link rel="stylesheet" type="text/css" href="style.css"> -<meta http-equiv="content-type" content="text/html; charset=UTF-8"> -</head> -<body bgcolor="#FFFFFF"> -<H1><a name="Modula3">31 SWIG and Modula-3</a></H1> -<!-- INDEX --> -<div class="sectiontoc"> -<ul> -<li><a href="#Modula3_modula3_overview">Overview</a> -<ul> -<li><a href="#Modula3_motivation">Motivation</a> -</ul> -<li><a href="#Modula3_conception">Conception</a> -<ul> -<li><a href="#Modula3_cinterface">Interfaces to C libraries</a> -<li><a href="#Modula3_cppinterface">Interfaces to C++ libraries</a> -</ul> -<li><a href="#Modula3_preliminaries">Preliminaries</a> -<ul> -<li><a href="#Modula3_compilers">Compilers</a> -<li><a href="#Modula3_commandline">Additional Commandline Options</a> -</ul> -<li><a href="#Modula3_typemaps">Modula-3 typemaps</a> -<ul> -<li><a href="#Modula3_inoutparam">Inputs and outputs</a> -<li><a href="#Modula3_ordinals">Subranges, Enumerations, Sets</a> -<li><a href="#Modula3_class">Objects</a> -<li><a href="#Modula3_imports">Imports</a> -<li><a href="#Modula3_exceptions">Exceptions</a> -<li><a href="#Modula3_typemap_example">Example</a> -</ul> -<li><a href="#Modula3_hints">More hints to the generator</a> -<ul> -<li><a href="#Modula3_features">Features</a> -<li><a href="#Modula3_pragmas">Pragmas</a> -</ul> -<li><a href="#Modula3_remarks">Remarks</a> -</ul> -</div> -<!-- INDEX --> - - - -<p> -This chapter describes SWIG's support for -<a href="http://modula3.org/">Modula-3</a>. -You should be familiar with the -<a href="SWIG.html#SWIG">basics</a> -of SWIG, -especially -<a href="Typemaps.html#Typemaps">typemaps</a>. -</p> - -<H2><a name="Modula3_modula3_overview">31.1 Overview</a></H2> - - -<p> -Modula-3 is a compiled language in the tradition of Niklaus Wirth's Modula 2, -which is in turn a successor to Pascal. -</p> - -<p> -SWIG's Modula-3 support is currently very basic and highly experimental! -Many features are still not designed satisfyingly -and I need more discussion about the odds and ends. -Don't rely on any feature, incompatible changes are likely in the future! -However, the Modula-3 generator was already useful for interfacing -to the libraries: -</p> - -<ol> -<li> -<a href="http://www.elegosoft.com/cgi-bin/cvsweb.cgi/cm3/m3-libs/plplot/"> -PLPlot -</a> -</li> -<li> -<a href="http://www.elegosoft.com/cgi-bin/cvsweb.cgi/cm3/m3-libs/fftw/"> -FFTW -</a> -</li> -</ol> - -<H3><a name="Modula3_motivation">31.1.1 Motivation</a></H3> - - -<p> -Although it is possible to write Modula-3 code that performs as well as C/C++ -most existing libraries are not written in Modula-3 but in C or C++, and -even libraries in other languages may provide C header files. -</p> - -<p> -Fortunately Modula-3 can call C functions, but you have to write Modula-3 -interfaces to them, and to make things comfortable you will also need -wrappers that convert between high-level features of Modula-3 (garbage -collecting, exceptions) and the explicit tracking of allocated memory and -exception codes used by C APIs. -</p> - -<p> -SWIG converts C headers to Modula-3 interfaces for you, and using typemaps -you can pass <tt>TEXT</tt>s or open arrays, and convert error return codes -into exceptions. -</p> - -<p> -If the library API is ill designed -writing appropriate typemaps can still be time-consuming. -E.g. C programmers are very creative to work-around -missing data types like (real) enumerations and sets. -You should turn such work-arounds back to the Modula-3 way -otherwise you lose static safety and consistency. -</p> - -<p> -Without SWIG you would probably never consider trying to call C++ libraries -from Modula-3, but with SWIG this is becomes feasible. -SWIG can generate C wrappers to C++ functions and object methods -that may throw exceptions, and then wrap these C wrappers for Modula-3. -To make it complete you can then hide the C interface with Modula-3 classes and -exceptions. -</p> - -<p> -SWIG allows you to call C and C++ libraries from Modula-3 (even with call back -functions), but it doesn't allow you to easily integrate a Modula-3 module into -a C/C++ project. -</p> - -<H2><a name="Modula3_conception">31.2 Conception</a></H2> - - -<H3><a name="Modula3_cinterface">31.2.1 Interfaces to C libraries</a></H3> - - -<p> -Modula-3 has integrated support for calling C functions. -This is also extensively used by the standard Modula-3 libraries -to call OS functions. -The Modula-3 part of SWIG and the corresponding SWIG library -modula3.swg -contain code that uses these features. -Because of the built-in support there is no need -for calling the SWIG kernel to generate wrappers written in C. -All conversion and argument checking can be done in Modula-3 -and the interfacing is quite efficient. -All you have to do is to write pieces of Modula-3 code -that SWIG puts together. -</p> - -<table border summary="Modula-3 C library support"> -<tr><th colspan=2>C library support integrated in Modula-3<th></tr> -<tr> -<td>Pragma <tt><* EXTERNAL *></tt></td> -<td>Precedes a declaration of a PROCEDURE that is implemented -in an external library instead of a Modula-3 module.</td> -</tr> -<tr> -<td>Pragma <tt><* CALLBACK *></tt></td> -<td>Precedes a declaration of a PROCEDURE that should be called -by external library code.</td> -</tr> -<tr> -<td>Module <tt>Ctypes</tt></td> -<td>Contains Modula-3 types that match some basic C types.</td> -</tr> -<tr> -<td>Module <tt>M3toC</tt></td> -<td>Contains routines that convert between Modula-3's <tt>TEXT</tt> type -and C's <tt>char *</tt> type.</td> -</tr> -</table> - -<p> -In each run of SWIG the Modula-3 part -generates several files: -</p> -<table border summary="Modula-3 generated files"> -<tr> - <th>Module name scheme</th> - <th>Identifier for <tt>%insert</tt></th> - <th>Description</th> -</tr> -<tr> - <td>Module<tt>Raw.i3</tt></td> - <td><tt>m3rawintf</tt></td> - <td>Declaration of types that are equivalent to those of the C library, - <tt>EXTERNAL</tt> procedures as interface to the C library functions</td> -</tr> -<tr> - <td>Module<tt>Raw.m3</tt></td> - <td><tt>m3rawimpl</tt></td> - <td>Almost empty.</td> -</tr> -<tr> - <td>Module<tt>.i3</tt></td> - <td><tt>m3wrapintf</tt></td> - <td>Declaration of comfortable wrappers to the C library functions.</td> -</tr> -<tr> - <td>Module<tt>.m3</tt></td> - <td><tt>m3wrapimpl</tt></td> - <td>Implementation of the wrappers that - convert between Modula-3 and C types, - check for validity of values, - hand-over resource management to the garbage collector using <tt>WeakRef</tt>s - and raises exceptions.</td> -</tr> -<tr> - <td><tt>m3makefile</tt></td> - <td><tt>m3makefile</tt></td> - <td>Add the modules above to the Modula-3 project and - specify the name of the Modula-3 wrapper library - to be generated. - - Today I'm not sure if it is a good idea - to create a <tt>m3makefile</tt> in each run, - because SWIG must be started for each Modula-3 module it creates. - Thus the m3makefile is overwritten each time. :-( - </td> -</tr> -</table> - -<p> -Here's a scheme of how the function calls to Modula-3 wrappers -are redirected to C library functions: -</p> - -<table summary="Modula-3 C library"> -<tr> - <td align=center> - Modula-3 wrapper<br> - Module<tt>.i3</tt><br> - generated by Modula-3 part of SWIG - </td> - <td></td> - <td align=center></td> -</tr> -<tr> - <td align=center> - <!-- pre tag overrides centering --> - |<br> - v - </td> - <td></td> - <td align=center></td> -</tr> -<tr> - <td align=center> - Modula-3 interface to C<br> - Module<tt>Raw.i3</tt><br> - generated by Modula-3 part of SWIG - </td> - <td>--></td> - <td align=center> - C library - </td> -</tr> -</table> - - -<p> -I have still no good conception how one can split C library interfaces -into type oriented interfaces. -A Module in Modula-3 represents an Abstract DataType -(or call it a static classes, i.e. a class without virtual methods). -E.g. if you have a principal type, say <tt>Database</tt>, -it is good Modula-3 style to set up one Module with the name <tt>Database</tt> -where the database type is declared with the name <tt>T</tt> -and where all functions are declared that operates on it. -</p> - -<p> -The normal operation of SWIG is to generate a fixed set of files per call. -To generate multiple modules one has to write one SWIG interface -(different SWIG interfaces can share common data) per module. -Identifiers belonging to a different module may ignored (<tt>%ignore</tt>) -and the principal type must be renamed (<tt>%typemap</tt>). -</p> - - -<H3><a name="Modula3_cppinterface">31.2.2 Interfaces to C++ libraries</a></H3> - - -<p> -Interfaces to C++ files are much more complicated and -there are some more design decisions that are not made, yet. -Modula-3 has no support for C++ functions -but C++ compilers should support generating C++ functions -with a C interface. -</p> - -<p> -Here's a scheme of how the function calls to Modula-3 wrappers -are redirected to C library functions: -</p> - -<table summary="Modula-3 C++ library"> -<tr> - <td align=center> - Modula-3 wrapper<br> - Module<tt>.i3</tt><br> - generated by Modula-3 part of SWIG - </td> - <td></td> - <td align=center>C++ library</td> -</tr> -<tr> - <td align=center> - <!-- pre tag overrides centering --> - |<br> - v - </td> - <td></td> - <td align=center> - ^<br> - | - </td> -</tr> -<tr> - <td align=center> - Modula-3 interface to C<br> - Module<tt>Raw.i3</tt><br> - generated by Modula-3 part of SWIG - </td> - <td>--></td> - <td align=center> - C interface to C++<br> - module<tt>_wrap.cxx</tt><br> - generated by the SWIG core - </td> -</tr> -</table> - -<p> -Wrapping C++ libraries arises additional problems: -</p> -<ul> -<li> -Is it sensible to wrap C++ classes with Modula-3 classes? -</li> -<li> -How to find the wrapping Modula-3 class -for a class pointer that is returned by a C++ routine? -</li> -<li> -How to deal with multiple inheritance -which was neglected for Modula-3 for good reasons? -</li> -<li> -Is it possible to sub-class C++ classes with Modula-3 code? -This issue is addressed by directors, -a feature that was experimentally added to some Language modules -like -<a href="Java.html#Java_directors">Java</a> and -<a href="Python.html#Python_directors">Python</a>. -</li> -<li> -How to manage storage with the garbage collector of Modula-3? -Support for -<a href="Customization.html#Customization_ownership"> -<tt>%newobject</tt> and <tt>%typemap(newfree)</tt></a> -isn't implemented, yet. -What's about resources that are managed by the garbage collector -but shall be passed back to the storage management of the C++ library? -This is a general issue which is not solved in a satisfying fashion -as far as I know. -</li> -<li> -How to turn C++ exceptions into Modula-3 exceptions? -There's also no support for -<a href="Customization.html#Customization_exception"> -<tt>%exception</tt></a>, yet. -</li> -</ul> - -<p> -Be warned: -There is no C++ library I wrote a SWIG interface for, -so I'm not sure if this is possible or sensible, yet. -</p> - -<H2><a name="Modula3_preliminaries">31.3 Preliminaries</a></H2> - - -<H3><a name="Modula3_compilers">31.3.1 Compilers</a></H3> - - -<p> -There are different Modula-3 compilers around: -cm3, pm3, ezm3, Klagenfurth Modula-3, Cambridge Modula-3. -SWIG itself does not contain compiler specific code -but the modula3.swg library file -may do so. -For testing examples I use Critical Mass cm3. -</p> - - -<H3><a name="Modula3_commandline">31.3.2 Additional Commandline Options</a></H3> - - -<p> -There are some experimental command line options -that prevent SWIG from generating interface files. -Instead files are emitted that may assist you -when writing SWIG interface files. -</p> - -<table border summary="Modula-3 specific options"> -<tr> -<th>Modula-3 specific options</th> -<th>Description</th> -</tr> - -<tr> -<td valign=top>-generateconst <file></td> -<td> -Disable generation of interfaces and wrappers. -Instead write code for computing numeric values of constants -to the specified file. -<br> -C code may contain several constant definitions -written as preprocessor macros. -Other language modules of SWIG use -compute-once-use-readonly variables or -functions to wrap such definitions. -All of them can invoke C code dynamically -for computing the macro values. -But if one wants to turn them into Modula-3 -integer constants, enumerations or set types, -the values of these expressions has to be known statically. -Although definitions like <tt>(1 << FLAG_MAXIMIZEWINDOW)</tt> -must be considered as good C style -they are hard to convert to Modula-3 -since the value computation can use every feature of C. -<br> -Thus I implemented these switch -to extract all constant definitions -and write a C program that output the values of them. -It works for numeric constants only -and treats all of them as <tt>double</tt>. -Future versions may generate a C++ program -that can detect the type of the macros -by overloaded output functions. -Then strings can also be processed. -</td> -</tr> - -<tr> -<td valign=top>-generaterename <file></td> -<td> -Disable generation of interfaces and wrappers. -Instead generate suggestions for <tt>%rename</tt>. -<br> -C libraries use a naming style -that is neither homogeneous nor similar to that of Modula-3. -C function names often contain a prefix denoting the library -and some name components separated by underscores -or capitalization changes. -To get library interfaces that are really Modula-3 like -you should rename the function names with the <tt>%rename</tt> directive. -This switch outputs a list of such directives -with a name suggestion generated by a simple heuristic. -</td> -</tr> - -<tr> -<td valign=top>-generatetypemap <file></td> -<td> -Disable generation of interfaces and wrappers. -Instead generate templates for some basic typemaps. -</td> -</tr> -</table> - -<H2><a name="Modula3_typemaps">31.4 Modula-3 typemaps</a></H2> - - -<H3><a name="Modula3_inoutparam">31.4.1 Inputs and outputs</a></H3> - - -<p> -Each C procedure has a bunch of inputs and outputs. -Inputs are passed as function arguments, -outputs are updated referential arguments and -the function value. -</p> - -<p> -Each C type can have several typemaps -that apply only in case if a type is used -for an input argument, for an output argument, -or for a return value. -A further typemap may specify -the direction that is used for certain parameters. -I have chosen this separation -in order to be able to write general typemaps for the modula3.swg typemap library. -In the library code the final usage of the type is not known. -Using separate typemaps for each possible use -allows appropriate definitions for each case. -If these pre-definitions are fine -then the direction of the function parameter -is the only hint the user must give. -</p> - -<p> -The typemaps specific to Modula-3 have a common name scheme: -A typemap name starts with "m3", -followed by "raw" or "wrap" -depending on whether it controls the generation -of the Module<tt>Raw.i3</tt> or the Module<tt>.i3</tt>, respectively. -It follows an "in" for typemaps applied to input argument, -"out" for output arguments, "arg" for all kind of arguments, -"ret" for returned values. -</p> - -<p> -The main task of SWIG is to build wrapper function, -i.e. functions that convert values between C and Modula-3 -and call the corresponding C function. -Modula-3 wrapper functions generated by SWIG -consist of the following parts: -</p> -<ul> -<li>Generate <tt>PROCEDURE</tt> signature.</li> -<li>Declare local variables.</li> -<li>Convert input values from Modula-3 to C.</li> -<li>Check for input value integrity.</li> -<li>Call the C function.</li> -<li>Check returned values, e.g. error codes.</li> -<li>Convert and write back values into Modula-3 records.</li> -<li>Free temporary storage.</li> -<li>Return values.</li> -</ul> - -<table border summary="Modula-3 typemaps"> -<tr> - <th>Typemap</th> - <th>Example</th> - <th>Description</th> -</tr> -<tr> - <td>m3wrapargvar</td> - <td><tt>$1: INTEGER := $1_name;</tt></td> - <td> - Declaration of some variables needed for temporary results. - </td> -</tr> -<tr> - <td>m3wrapargconst</td> - <td><tt>$1 = "$1_name";</tt></td> - <td> - Declaration of some constant, maybe for debug purposes. - </td> -</tr> -<tr> - <td>m3wrapargraw</td> - <td><tt>ORD($1_name)</tt></td> - <td> - The expression that should be passed as argument to the raw Modula-3 interface function. - </td> -</tr> -<tr> - <td>m3wrapargdir</td> - <td><tt>out</tt></td> - <td> - Referential arguments can be used for input, output, update. - ??? - </td> -</tr> -<tr> - <td>m3wrapinmode</td> - <td><tt>READONLY</tt></td> - <td> - One of Modula-3 parameter modes - <tt>VALUE</tt> (or empty), - <tt>VAR</tt>, - <tt>READONLY</tt> - </td> -</tr> -<tr> - <td>m3wrapinname</td> - <td></td> - <td> - New name of the input argument. - </td> -</tr> -<tr> - <td>m3wrapintype</td> - <td></td> - <td> - Modula-3 type of the input argument. - </td> -</tr> -<tr> - <td>m3wrapindefault</td> - <td></td> - <td> - Default value of the input argument - </td> -</tr> -<tr> - <td>m3wrapinconv</td> - <td><tt>$1 := M3toC.SharedTtoS($1_name);</tt></td> - <td> - Statement for converting the Modula-3 input value to C compliant value. - </td> -</tr> -<tr> - <td>m3wrapincheck</td> - <td><tt>IF Text.Length($1_name) > 10 THEN RAISE E("str too long"); END;</tt></td> - <td> - Check the integrity of the input value. - </td> -</tr> -<tr> - <td>m3wrapoutname</td> - <td></td> - <td> - Name of the <tt>RECORD</tt> field to be used for returning multiple values. - This applies to referential output arguments that shall be turned - into return values. - </td> -</tr> -<tr> - <td>m3wrapouttype</td> - <td></td> - <td> - Type of the value that is returned instead of a referential output argument. - </td> -</tr> -<tr> - <td>m3wrapoutconv</td> - <td></td> - <td> - </td> -</tr> -<tr> - <td>m3wrapoutcheck</td> - <td></td> - <td> - </td> -</tr> -<tr> - <td>m3wrapretraw</td> - <td></td> - <td> - </td> -</tr> -<tr> - <td>m3wrapretname</td> - <td></td> - <td> - </td> -</tr> -<tr> - <td>m3wraprettype</td> - <td></td> - <td> - </td> -</tr> -<tr> - <td>m3wrapretvar</td> - <td></td> - <td> - </td> -</tr> -<tr> - <td>m3wrapretconv</td> - <td></td> - <td> - </td> -</tr> -<tr> - <td>m3wrapretcheck</td> - <td></td> - <td> - </td> -</tr> -<tr> - <td>m3wrapfreearg</td> - <td><tt>M3toC.FreeSharedS(str, arg1);</tt></td> - <td> - Free resources that were temporarily used in the wrapper. - Since this step should never be skipped, - SWIG will put it in the <tt>FINALLY</tt> branch - of a <tt>TRY .. FINALLY</tt> structure. - </td> -</tr> -</table> - - -<H3><a name="Modula3_ordinals">31.4.2 Subranges, Enumerations, Sets</a></H3> - - -<p> -Subranges, enumerations, and sets are machine oriented types -that make Modula very strong and expressive compared -with the type systems of many other languages. -</p> - -<ul> -<li> -Subranges are used for statically restricted choices of integers. -</li> -<li> -Enumerations are used for named choices. -</li> -<li> -Sets are commonly used for flag (option) sets. -</li> -</ul> - -<p> -Using them extensively makes Modula code very safe and readable. -</p> - -<p> -C supports enumerations, too, but they are not as safe as the ones of Modula. -Thus they are abused for many things: -For named choices, for integer constant definitions, for sets. -To make it complete every way of defining a value in C -(<tt>#define</tt>, <tt>const int</tt>, <tt>enum</tt>) -is somewhere used for defining something -that must be handled completely different in Modula-3 -(<tt>INTEGER</tt>, enumeration, <tt>SET</tt>). -</p> - -<p> -I played around with several <tt>%feature</tt>s and <tt>%pragma</tt>s -that split the task up into converting -the C bit patterns (integer or bit set) -into Modula-3 bit patterns (integer or bit set) -and change the type as requested. -See the corresponding example in the -Examples/modula3/enum/example.i file. -This is quite messy and not satisfying. -So the best what you can currently do is -to rewrite constant definitions manually. -Though this is a tedious work -that I'd like to automate. -</p> - - -<H3><a name="Modula3_class">31.4.3 Objects</a></H3> - - -<p> -Declarations of C++ classes are mapped to <tt>OBJECT</tt> types -while it is tried to retain the access hierarchy -"public - protected - private" using partial revelation. -Though the example in -Examples/modula3/class/example.i -is not really useful, yet. -</p> - - -<H3><a name="Modula3_imports">31.4.4 Imports</a></H3> - - -<p> -Pieces of Modula-3 code provided by typemaps -may contain identifiers from foreign modules. -If the typemap <tt>m3wrapinconv</tt> for <tt>blah *</tt> -contains code using the function <tt>M3toC.SharedTtoS</tt> -you may declare <tt>%typemap("m3wrapinconv:import") blah * %{M3toC%}</tt>. -Then the module <tt>M3toC</tt> is imported -if the <tt>m3wrapinconv</tt> typemap for <tt>blah *</tt> -is used at least once. -Use <tt>%typemap("m3wrapinconv:import") blah * %{MyConversions AS M3toC%}</tt> -if you need module renaming. -Unqualified import is not supported. -</p> - -<p> -It is cumbersome to add this typemap to each piece of Modula-3 code. -It is especially useful when writing general typemaps -for the modula3.swg typemap library. -For a monolithic module you might be better off -if you add the imports directly: -</p> - -<div class="code"> -<pre> -%insert(m3rawintf) %{ -IMPORT M3toC; -%} -</pre></div> - - -<H3><a name="Modula3_exceptions">31.4.5 Exceptions</a></H3> - - -<p> -Modula-3 provides another possibility -of an output of a function: exceptions. -</p> - -<p> -Any piece of Modula-3 code that SWIG inserts -due to a typemap can raise an exception. -This way you can also convert an error code -from a C function into a Modula-3 exception. -</p> - -<p> -The <tt>RAISES</tt> clause is controlled -by typemaps with the <tt>throws</tt> extension. -If the typemap <tt>m3wrapinconv</tt> for <tt>blah *</tt> -contains code that may raise the exceptions <tt>OSError.E</tt> -you should declare -<tt>%typemap("m3wrapinconv:throws") blah * %{OSError.E%}</tt>. -</p> - -<H3><a name="Modula3_typemap_example">31.4.6 Example</a></H3> - - -<p> -The generation of wrappers in Modula-3 needs very fine control -to take advantage of the language features. -Here is an example of a generated wrapper -where almost everything is generated by a typemap: -</p> - -<div class="code"><pre> -<I> (* %relabel m3wrapinmode m3wrapinname m3wrapintype m3wrapindefault *)</I> - PROCEDURE Name (READONLY str : TEXT := "" ) -<I> (* m3wrapoutcheck:throws *)</I> - : NameResult RAISES {E} = - CONST - arg1name = "str"; <I>(* m3wrapargconst *)</I> - VAR - arg0 : C.char_star; <I>(* m3wrapretvar *)</I> - arg1 : C.char_star; <I>(* m3wrapargvar *)</I> - arg2 : C.int; - result : RECORD -<I> (*m3wrapretname m3wraprettype*)</I> - unixPath : TEXT; -<I> (*m3wrapoutname m3wrapouttype*)</I> - checksum : CARDINAL; - END; - BEGIN - TRY - arg1 := M3toC.SharedTtoS(str); <I>(* m3wrapinconv *)</I> - IF Text.Length(arg1) > 10 THEN <I>(* m3wrapincheck *)</I> - RAISE E("str too long"); - END; -<I> (* m3wrapretraw m3wrapargraw *)</I> - arg0 := MessyToUnix (arg1, arg2); - result.unixPath := M3toC.CopyStoT(arg0); <I>(* m3wrapretconv *)</I> - result.checksum := arg2; <I>(* m3wrapoutconv *)</I> - IF result.checksum = 0 THEN <I>(* m3wrapoutcheck *)</I> - RAISE E("invalid checksum"); - END; - FINALLY - M3toC.FreeSharedS(str, arg1); <I>(* m3wrapfreearg *)</I> - END; - END Name; -</pre></div> - - -<H2><a name="Modula3_hints">31.5 More hints to the generator</a></H2> - - -<H3><a name="Modula3_features">31.5.1 Features</a></H3> - - -<table border summary="Modula-3 features"> -<tr> - <th>Feature</th> - <th>Example</th> - <th>Description</th> -</tr> -<tr> - <td>multiretval</td> - <td><tt>%m3multiretval get_box;</tt> or - <tt>%feature("modula3:multiretval") get_box;</tt></td> - <td>Let the denoted function return a <tt>RECORD</tt> - rather than a plain value. - This <tt>RECORD</tt> contains all arguments with "out" direction - including the return value of the C function (if there is one). - If more than one argument is "out" - then the function <b>must</b> have the <tt>multiretval</tt> feature activated, - but it is explicitly requested from the user to prevent mistakes.</td> -</tr> -<tr> - <td>constnumeric</td> - <td><tt>%constnumeric(12) twelve;</tt> or - <tt>%feature("constnumeric", "12") twelve;</tt></td> - <td>This feature can be used to tell Modula-3's back-end of SWIG - the value of an identifier. - This is necessary in the cases - where it was defined by a non-trivial C expression. - This feature is used by the - <tt>-generateconst</tt> <a href="#Modula3_commandline">option</a>. - In future it may be generalized to other kind of values - such as strings. - </td> -</tr> -</table> - -<H3><a name="Modula3_pragmas">31.5.2 Pragmas</a></H3> - - -<table border summary="Modula-3 pragmas"> -<tr> - <th>Pragma</th> - <th>Example</th> - <th>Description</th> -</tr> -<tr> - <td>unsafe</td> - <td><tt>%pragma(modula3) unsafe="true";</tt></td> - <td>Mark the raw interface modules as <tt>UNSAFE</tt>. - This will be necessary in many cases.</td> -</tr> -<tr> - <td>library</td> - <td><tt>%pragma(modula3) library="m3fftw";</tt></td> - <td>Specifies the library name for the wrapper library to be created. - It should be distinct from the name of the library to be wrapped.</td> -</tr> -</table> - -<H2><a name="Modula3_remarks">31.6 Remarks</a></H2> - - -<ul> -<li> -The Modula-3 part of SWIG doesn't try to generate nicely formatted code. -If you need to read the generated code, use <tt>m3pp</tt> to postprocess the -Modula files. -</li> -</ul> - -</body> -</html> diff --git a/Doc/Manual/Perl5.html b/Doc/Manual/Perl5.html index 1e7bd9f86..85c2545cf 100644 --- a/Doc/Manual/Perl5.html +++ b/Doc/Manual/Perl5.html @@ -2243,7 +2243,7 @@ can be done using the <tt>EXTEND()</tt> macro as in: EXTEND(sp, 1); /* Extend the stack by 1 object */ } $result = sv_newmortal(); - sv_setiv($target, (IV) *($1)); + sv_setiv($result, (IV) *($1)); argvi++; } </pre></div> diff --git a/Doc/Manual/Php.html b/Doc/Manual/Php.html index 09c514e94..5aea878b2 100644 --- a/Doc/Manual/Php.html +++ b/Doc/Manual/Php.html @@ -51,12 +51,12 @@ <p> In this chapter, we discuss SWIG's support of PHP. SWIG currently supports -generating wrappers for PHP7. Support for PHP5 was removed in SWIG 4.0.0 -and support for PHP4 was removed in SWIG 1.3.37. +generating wrappers for PHP7 and PHP8. Support for PHP5 was removed in SWIG +4.0.0 and support for PHP4 was removed in SWIG 1.3.37. </p> <p> -Currently any PHP7 release should work. +Currently any PHP7 or PHP8 release should work. </p> <p> @@ -84,16 +84,21 @@ swig -php7 example.i </pre></div> <p> -This will produce 3 files example_wrap.c, php_example.h and -example.php. The first file, <tt>example_wrap.c</tt> contains all of +This will produce 2 files: example_wrap.c and php_example.h. +The first file, <tt>example_wrap.c</tt> contains all of the C code needed to build a PHP extension. The second file, <tt>php_example.h</tt> contains the header information needed if you wish to statically link the extension into the php interpreter. -The third file, -<tt>example.php</tt> can be included by PHP scripts. It attempts to -dynamically load the extension and contains extra php code specified -in the interface file. If wrapping C++ code with PHP classes, it will -also contain PHP class wrappers. +</p> + +<p> +If the interface file uses <tt>%pragma(php) include=</tt>... or +<tt>%pragma(php) code=</tt>... then SWIG will also generate a third file, +<tt>example.php</tt> to contain what these specify. In SWIG < 4.1.0, +this third file was always generated as it defined the PHP classes, etc +(but this is now done via C code in <tt>example_wrap.c</tt>) and also +contained code to dynamically load the extension (but this used the +PHP <tt>dl()</tt> function, which isn't recommended nowadays). </p> <p> @@ -139,47 +144,43 @@ least work for Linux though): <p> To test the extension from a PHP script, you first need to tell PHP to -load it. To do this, add a line like this to the <tt>[PHP]</tt> section of -<tt>php.ini</tt>: +load it. Assuming you're using PHP 7.2 or higher, the recommended (and +simplest!) way to do this is to copy it to PHP's default extension directory +and add a line like this to the <tt>[PHP]</tt> section of <tt>php.ini</tt>: </p> <div class="code"><pre> - extension=/path/to/modulename.so + extension=modulename </pre></div> <p> -If the module is in PHP's default extension directory, you can omit the path. -</p> - -<p> -For some SAPIs (for example, the CLI SAPI) you can instead use the -<a href="https://www.php.net/manual/en/function.dl.php">dl() function</a> to load -an extension at run time, by adding a line like this to the start of each -PHP script which uses your extension: +PHP < 7.2 doesn't support loading by just the module name, so you need +to specify the filename of the module to be specified, which varies +between platforms. And for any PHP version, if the module is not in PHP's +default extension directory, you also need to specify the path, for example: </p> <div class="code"><pre> - dl("/path/to/modulename.so"); // Load the module + extension=/path/to/modulename.so </pre></div> <p> -But note that <tt>dl()</tt> isn't supported when running PHP through a -webserver - you'll need to use <tt>extension</tt> in <tt>php.ini</tt> as -described above. -</p> - -<p> -The PHP module which SWIG generates will also attempt to do the <tt>dl()</tt> -call for you if the extension isn't already loaded: +If you're using the PHP CLI SAPI it's possible (but not recommended) to use the +<a href="https://www.php.net/manual/en/function.dl.php">dl() function</a> to +load an extension at run time, by adding a line like this to the start of each +PHP script which uses your extension: </p> <div class="code"><pre> - include("example.php"); + dl("/path/to/modulename.so"); // Load the module </pre></div> <p> -This PHP module also defines the PHP classes for the wrapped API, so you'll -almost certainly want to include it anyway. +But to do this portably you need to take into account that pathnames and the +filename extension vary by platform, and for security reasons PHP no longer +supports <tt>dl()</tt> when running PHP through a webserver. Overall it's +better to instead use <tt>extension</tt> in <tt>php.ini</tt> as described +above. </p> <H2><a name="Php_nn2">32.2 Basic PHP interface</a></H2> @@ -219,24 +220,19 @@ you can access the constants in your PHP script like this, </p> <div class="code"><pre> -include("example.php"); - echo "PI = " . PI . "\n"; - echo "E = " . E . "\n"; - </pre> </div> <p> -There's one peculiarity of how constants work in PHP which it is useful -to note (this is not specific to SWIG though) - if you try to use an undeclared -constant, PHP will emit a warning (or a notice in PHP 7.1 and earlier) and then -expand the constant to a string version of the constant's name. Unfortunately -it is easy to miss the warning message if you're using PHP in a webserver as -it will probably end up in error.log or similar. Apparently this will throw -an Error in a future version of PHP, but until then it's something to be -aware of. +There's one peculiarity of how constants work in PHP prior to PHP 8 +which it is useful to note (this is not specific to SWIG though) - if you try +to use an undeclared constant, PHP will emit a warning (or a notice in PHP 7.1 +and earlier) and then expand the constant to a string version of the constant's +name. Unfortunately it is easy to miss the warning message if you're using PHP +in a webserver as it will probably end up in error.log or similar. PHP 8.0 +made this an error. </p> <p> @@ -256,8 +252,6 @@ accessed incorrectly in PHP, <div class="code"> <pre> -include("example.php"); - if(EASY_TO_MISPEL) { ... } else { @@ -298,7 +292,6 @@ is accessed as follows: </p> <div class="code"><pre> -include("example.php"); print seki_get(); seki_set( seki_get() * 2); # The C variable is now 4. print seki_get(); @@ -306,8 +299,10 @@ print seki_get(); <p> SWIG supports global variables of all C datatypes including pointers -and complex objects. Additional types can be supported by using the -<tt>varinit</tt> typemap. +and complex objects. To support additional types, you just need to +supply the standard <tt>in</tt> and <tt>out</tt> typemaps, which get +used because of the wrapping as <tt>_get()</tt> and <tt>_set()</tt> +functions. </p> <p> @@ -342,7 +337,6 @@ Will be accessed in PHP like this : </p> <div class="code"><pre> -include("example.php"); $a = foo(2); $b = bar(3.5, -1.5); $c = bar(3.5); # Use default argument for 2nd parameter @@ -432,10 +426,12 @@ taking the integer argument. <H3><a name="Php_nn2_5">32.2.5 Pointers and References</a></H3> - <p> -Pointers to C/C++ objects are represented -as PHP resources, rather like MySQL connection handles. +Since SWIG 4.1.0, SWIG wraps C/C++ classes directly with PHP objects. +Pointers to other types are also wrapped as PHP objects - mostly this is an +implementation detail, but it's visible from PHP via <tt>is_object()</tt> and +similar. In earlier SWIG versions, PHP resources were used to wrap both +classes and pointers to other types. </p> <p> @@ -467,8 +463,6 @@ This will result in the following usage in PHP: <div class="code"><pre> <?php -include("example.php"); - $in1=copy_intp(3); $in2=copy_intp(5); $result=new_intp(); @@ -476,7 +470,6 @@ $result=new_intp(); add( $in1, $in2, $result ); echo "The sum " . intp_value($in1) . " + " . intp_value($in2) . " = " . intp_value( $result) . "\n"; -?> </pre></div> <p> @@ -501,14 +494,11 @@ This will result in the following usage in PHP: <div class="code"><pre> <?php -include("example.php"); - $in1 = 3; $in2 = 5; $result= add($in1, $in2); # Note using variables for the input is unnecessary. echo "The sum $in1 + $in2 = $result\n"; -?> </pre></div> <p> @@ -539,15 +529,12 @@ This will result in the following usage in PHP: <div class="code"><pre> <?php -include("example.php"); - $in1 = 3; $in2 = 5; $result = 0; add($in1, $in2, $result); echo "The sum $in1 + $in2 = $result\n"; -?> </pre></div> <p> @@ -572,11 +559,16 @@ variable, or assigning <tt>NULL</tt> to a variable. <p> -SWIG defaults to wrapping C++ structs and classes with PHP classes - this -is done by generating a PHP wrapper script which defines proxy classes -which calls a set of flat functions which actually wrap the C++ class. -You can disable this wrapper layer by passing the command-line option -"-noproxy" in which case you'll just get the flat functions. +SWIG defaults to wrapping C++ structs and classes with PHP classes. +Since SWIG 4.1.0, this is done entirely via PHP's C API - earlier SWIG +versions generated a PHP wrapper script which defined proxy classes +which called a set of flat functions which actually wrapped the C++ class. +</p> + +<p> +If you don't want the class wrappers, you can pass the command-line option +"-noproxy" in which case you'll get C++ classes wrapped as flat functions +as described below. </p> <p> @@ -605,7 +597,6 @@ Would be used in the following way from PHP: <div class="code"><pre> <?php - require "vector.php"; $v = new Vector(); $v->x = 3; @@ -622,7 +613,6 @@ Would be used in the following way from PHP: $c->im = 0; # $c destructor called when $c goes out of scope. -?> </pre></div> <p> @@ -667,8 +657,8 @@ constructor to execute. </p> <p> -Because PHP uses reference counting to manage resources, simple -assignment of one variable to another such as: +Because PHP uses reference counting, simple assignment of one variable to +another such as: </p> <div class="code"><pre> @@ -721,8 +711,6 @@ would be accessed in PHP as, </p> <div class="code"><pre> -include("example.php"); - echo "There have now been " . Ko::threats() . " threats\n"; </pre></div> @@ -756,7 +744,6 @@ class Ko { would be executed in PHP as, <div class="code"><pre> -include("example.php"); Ko::threats(); </pre></div> @@ -783,9 +770,8 @@ If there are multiple interfaces, just list them separated by commas. <p> -To place PHP code in the generated "example.php" file one can use the -<b>code</b> pragma. The code is inserted after loading the shared -object. +You can get SWIG to generate an "example.php" file by specifying +the code to put in it using the <b>code</b> pragma. </p> <div class="code"><pre> @@ -883,7 +869,7 @@ into the request init (PHP_RINIT_FUNCTION) and request shutdown (PHP_RSHUTDOWN_F Proxy classes provide a more natural, object-oriented way to access extension classes. As described above, each proxy instance has an associated C++ instance, and method calls to the proxy are passed to the -C++ instance transparently via C wrapper functions. +C++ instance transparently. </p> <p> @@ -989,8 +975,6 @@ then at the PHP side you can define <div class="targetlang"> <pre> -require("mymodule.php"); - class MyFoo extends Foo { function one() { print "one from php\n"; @@ -1012,8 +996,8 @@ that derives from both the class in question and a special <tt>Swig::Director</tt> class. These new classes, referred to as director classes, can be loosely thought of as the C++ equivalent of the PHP proxy classes. The director classes store a pointer to their underlying -PHP object. Indeed, this is quite similar to the "_cPtr" and "thisown" -members of the PHP proxy classes. +PHP object. Indeed, this is quite similar to <tt>struct swig_object_wrapper</tt> +which is used to implement the PHP proxy classes. </p> <p> @@ -1068,12 +1052,12 @@ infinite loop. <p> One more point needs to be made about the relationship between director classes and proxy classes. When a proxy class instance is created in -PHP, SWIG creates an instance of the original C++ class and assigns it -to <tt>->_cPtr</tt>. This is exactly what happens without directors -and is true even if directors are enabled for the particular class in -question. When a class <i>derived</i> from a proxy class is created, -however, SWIG then creates an instance of the corresponding C++ director -class. The reason for this difference is that user-defined subclasses +PHP, SWIG creates an instance of the original C++ class and stores it +in the <tt>struct swig_object_wrapper</tt>. This is true whether or not +directors are enabled for the particular class in question. However +when a class <i>derived</i> from a proxy class is created, SWIG instead +creates an instance of the corresponding C++ director class. +The reason for this difference is that user-defined subclasses may override or extend methods of the original class, so the director class is needed to route calls to these methods correctly. For unmodified proxy classes, all methods are ultimately implemented in C++ @@ -1161,7 +1145,12 @@ should suffice in most cases: <div class="code"> <pre> %feature("director:except") { - if ($error == FAILURE) { +#if SWIG_VERSION >= 0x040100 + if ($error != NULL) +#else + if ($error == FAILURE) +#endif + { throw Swig::DirectorMethodException(); } } @@ -1169,6 +1158,20 @@ should suffice in most cases: </div> <p> +If you only need to support SWIG >= 4.1.0, you can just use the +<tt>($error != NULL)</tt> condition. +</p> + +<p> +In SWIG 4.1.0, <tt>$error</tt> was changed in the SWIG/PHP director +implementation to make it work more like how it does for other languages. +Previously, <tt>$error</tt> didn't actually indicate an exception, but instead +was only set to <tt>FAILURE</tt> if there was a problem calling the PHP method. +Now <tt>$error</tt> indicates if the PHP method threw a PHP exception, and +directorout typemaps for PHP no longer need to be gated by <tt>if (EG(exception))</tt>. +</p> + +<p> This code will check the PHP error state after each method call from a director into PHP, and throw a C++ exception if an error occurred. This exception can be caught in C++ to implement an error handler. diff --git a/Doc/Manual/Pike.html b/Doc/Manual/Pike.html deleted file mode 100644 index 2b8432399..000000000 --- a/Doc/Manual/Pike.html +++ /dev/null @@ -1,246 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> -<html> -<head> -<title>SWIG and Pike</title> -<link rel="stylesheet" type="text/css" href="style.css"> -<meta http-equiv="content-type" content="text/html; charset=UTF-8"> -</head> - -<body bgcolor="#ffffff"> -<H1><a name="Pike">37 SWIG and Pike</a></H1> -<!-- INDEX --> -<div class="sectiontoc"> -<ul> -<li><a href="#Pike_nn2">Preliminaries</a> -<ul> -<li><a href="#Pike_nn3">Running SWIG</a> -<li><a href="#Pike_nn4">Getting the right header files</a> -<li><a href="#Pike_nn5">Using your module</a> -</ul> -<li><a href="#Pike_nn6">Basic C/C++ Mapping</a> -<ul> -<li><a href="#Pike_nn7">Modules</a> -<li><a href="#Pike_nn8">Functions</a> -<li><a href="#Pike_nn9">Global variables</a> -<li><a href="#Pike_nn10">Constants and enumerated types</a> -<li><a href="#Pike_nn11">Constructors and Destructors</a> -<li><a href="#Pike_nn12">Static Members</a> -</ul> -</ul> -</div> -<!-- INDEX --> - - - -<p> -This chapter describes SWIG support for Pike. As of this writing, the -SWIG Pike module is still under development and is not considered -ready for prime time. The Pike module is being developed against the -Pike 7.4.10 release and may not be compatible with previous versions -of Pike. -</p> - -<p> -This chapter covers most SWIG features, but certain low-level details -are covered in less depth than in earlier chapters. At the very -least, make sure you read the "<a href="SWIG.html#SWIG">SWIG Basics</a>" -chapter.<br> -</p> - -<H2><a name="Pike_nn2">37.1 Preliminaries</a></H2> - - -<H3><a name="Pike_nn3">37.1.1 Running SWIG</a></H3> - - -<p> -Suppose that you defined a SWIG module such as the following: -</p> - -<div class="code"> - <pre>%module example<br><br>%{<br>#include "example.h"<br>%}<br><br>int fact(int n);<br></pre> -</div> - -<p> -To build a C extension module for Pike, run SWIG using the <tt>-pike</tt> option : -</p> - -<div class="code"> - <pre>$ <b>swig -pike example.i</b><br></pre> -</div> - -<p> -If you're building a C++ extension, be sure to add the <tt>-c++</tt> option: -</p> - -<div class="code"> - <pre>$ <b>swig -c++ -pike example.i</b><br></pre> -</div> - -<p> -This creates a single source file named <tt>example_wrap.c</tt> (or <tt>example_wrap.cxx</tt>, if you -ran SWIG with the <tt>-c++</tt> option). -The SWIG-generated source file contains the low-level wrappers that need -to be compiled and linked with the rest of your C/C++ application to -create an extension module. -</p> - -<p> -The name of the wrapper file is derived from the name of the input -file. For example, if the input file is <tt>example.i</tt>, the name -of the wrapper file is <tt>example_wrap.c</tt>. To change this, you -can use the <tt>-o</tt> option: -</p> - -<div class="code"> - <pre>$ <b>swig -pike -o pseudonym.c example.i</b><br></pre> -</div> -<H3><a name="Pike_nn4">37.1.2 Getting the right header files</a></H3> - - -<p> -In order to compile the C/C++ wrappers, the compiler needs to know the -path to the Pike header files. These files are usually contained in a -directory such as -</p> - -<div class="code"> - <pre>/usr/local/pike/7.4.10/include/pike<br></pre> -</div> - -<p> -There doesn't seem to be any way to get Pike itself to reveal the -location of these files, so you may need to hunt around for them. -You're looking for files with the names <tt>global.h</tt>, <tt>program.h</tt> -and so on. -</p> - -<H3><a name="Pike_nn5">37.1.3 Using your module</a></H3> - - -<p> -To use your module, simply use Pike's <tt>import</tt> statement: -</p> - -<div class="code"><pre> -$ <b>pike</b> -Pike v7.4 release 10 running Hilfe v3.5 (Incremental Pike Frontend) -> <b>import example;</b> -> <b>fact(4);</b> -(1) Result: 24 -</pre></div> - -<H2><a name="Pike_nn6">37.2 Basic C/C++ Mapping</a></H2> - - -<H3><a name="Pike_nn7">37.2.1 Modules</a></H3> - - -<p> -All of the code for a given SWIG module is wrapped into a single Pike -module. Since the name of the shared library that implements your -module ultimately determines the module's name (as far as Pike is -concerned), SWIG's <tt>%module</tt> directive doesn't really have any -significance. -</p> - -<H3><a name="Pike_nn8">37.2.2 Functions</a></H3> - - -<p> -Global functions are wrapped as new Pike built-in functions. For -example, -</p> - -<div class="code"><pre> -%module example - -int fact(int n); -</pre></div> - -<p> -creates a new built-in function <tt>example.fact(n)</tt> that works -exactly as you'd expect it to: -</p> - -<div class="code"><pre> -> <b>import example;</b> -> <b>fact(4);</b> -(1) Result: 24 -</pre></div> - -<H3><a name="Pike_nn9">37.2.3 Global variables</a></H3> - - -<p> -Global variables are currently wrapped as a pair of functions, one to get -the current value of the variable and another to set it. For example, the -declaration -</p> - -<div class="code"><pre> -%module example - -double Foo; -</pre></div> - -<p> -will result in two functions, <tt>Foo_get()</tt> and <tt>Foo_set()</tt>: -</p> - -<div class="code"><pre> -> <b>import example;</b> -> <b>Foo_get();</b> -(1) Result: 3.000000 -> <b>Foo_set(3.14159);</b> -(2) Result: 0 -> <b>Foo_get();</b> -(3) Result: 3.141590 -</pre></div> - -<H3><a name="Pike_nn10">37.2.4 Constants and enumerated types</a></H3> - - -<p> -Enumerated types in C/C++ declarations are wrapped as Pike constants, -not as Pike enums. -</p> - -<H3><a name="Pike_nn11">37.2.5 Constructors and Destructors</a></H3> - - -<p> -Constructors are wrapped as <tt>create()</tt> methods, and destructors are -wrapped as <tt>destroy()</tt> methods, for Pike classes. -</p> - -<H3><a name="Pike_nn12">37.2.6 Static Members</a></H3> - - -<p> -Since Pike doesn't support static methods or data for Pike classes, static -member functions in your C++ classes are wrapped as regular functions and -static member variables are wrapped as pairs of functions (one to get the -value of the static member variable, and another to set it). The names of -these functions are prepended with the name of the class. -For example, given this C++ class declaration: -</p> - -<div class="code"><pre> -class Shape -{ -public: - static void print(); - static int nshapes; -}; -</pre></div> - -<p> -SWIG will generate a <tt>Shape_print()</tt> method that invokes the static -<tt>Shape::print()</tt> member function, as well as a pair of methods, -<tt>Shape_nshapes_get()</tt> and <tt>Shape_nshapes_set()</tt>, to get and set -the value of <tt>Shape::nshapes</tt>. -</p> - -</body> -</html> diff --git a/Doc/Manual/Preprocessor.html b/Doc/Manual/Preprocessor.html index 51cc06378..7611ea40c 100644 --- a/Doc/Manual/Preprocessor.html +++ b/Doc/Manual/Preprocessor.html @@ -123,7 +123,7 @@ SWIGOCAML Defined when using OCaml SWIGOCTAVE Defined when using Octave SWIGPERL Defined when using Perl SWIGPHP Defined when using PHP (any version) -SWIGPHP7 Defined when using PHP7 +SWIGPHP7 Defined when using PHP 7 or later (with a compatible C API) SWIGPYTHON Defined when using Python SWIGR Defined when using R SWIGRUBY Defined when using Ruby diff --git a/Doc/Manual/Python.html b/Doc/Manual/Python.html index c132afc8a..1bd7b1e3c 100644 --- a/Doc/Manual/Python.html +++ b/Doc/Manual/Python.html @@ -1608,7 +1608,7 @@ public: </div> <p> -In Python, the static member can be access in three different ways: +In Python, the static member can be accessed in three different ways: </p> <div class="targetlang"> @@ -1616,7 +1616,7 @@ In Python, the static member can be access in three different ways: >>> example.Spam_foo() # Spam::foo() >>> s = example.Spam() >>> s.foo() # Spam::foo() via an instance ->>> example.Spam.foo() # Spam::foo(). Python-2.2 only +>>> example.Spam.foo() # Spam::foo() using Python-2.2 and later </pre> </div> @@ -1627,16 +1627,31 @@ last technique is only available in Python-2.2 and later versions. <p> Static member variables are currently accessed as global variables. This means, -they are accessed through <tt>cvar</tt> like this: +they are accessed through <tt>cvar</tt> or via an instance property: </p> <div class="targetlang"> <pre> ->>> print example.cvar.Spam_bar +>>> example.cvar.Spam_bar # Spam::bar +7 +>>> s = example.Spam() +>>> s.bar # Spam::bar via an instance property +7 +</pre> +</div> + +<p> +The <tt>-builtin</tt> option uses a metaclass to additionally provide access as follows: +</p> + +<div class="targetlang"> +<pre> +>>> example.Spam.bar # Spam::bar using -builtin option only 7 </pre> </div> + <H3><a name="Python_nn21">33.3.8 C++ inheritance</a></H3> diff --git a/Doc/Manual/R.html b/Doc/Manual/R.html index e44fe432c..9b05922fd 100644 --- a/Doc/Manual/R.html +++ b/Doc/Manual/R.html @@ -196,7 +196,7 @@ slices) <p> Wrapping of C++ classes for R works quite well. R has a special type, known as an external reference, that can be used as a pointer -to arbitary things, including C++ classes. The proxy layers generated +to arbitrary things, including C++ classes. The proxy layers generated for other classes are not required. </p> @@ -265,7 +265,7 @@ v2$Axles [1] 4 v1$Available [1] FALSE -# Set availabilty +# Set availability v1$Available <- TRUE v1$Available [1] TRUE diff --git a/Doc/Manual/SWIG.html b/Doc/Manual/SWIG.html index c54d117e0..876c0ac17 100644 --- a/Doc/Manual/SWIG.html +++ b/Doc/Manual/SWIG.html @@ -127,7 +127,7 @@ Supported Target Language Options -lua - Generate Lua wrappers -octave - Generate Octave wrappers -perl5 - Generate Perl 5 wrappers - -php7 - Generate PHP 7 wrappers + -php7 - Generate PHP 7 or later wrappers -python - Generate Python wrappers -r - Generate R (aka GNU S) wrappers -ruby - Generate Ruby wrappers @@ -2020,7 +2020,7 @@ and a more descriptive one, but the two functions are otherwise equivalent: <tr> <td><span style="white-space: nowrap;"><tt>regex:/pattern/subst/</tt></span></td> <td>String after (Perl-like) regex substitution operation. This function - allows to apply arbitrary regular expressions to the identifier names. The + allows applying arbitrary regular expressions to the identifier names. The <i>pattern</i> part is a regular expression in Perl syntax (as supported by the <a href="http://www.pcre.org/">Perl Compatible Regular Expressions (PCRE)</a>) library and the <i>subst</i> string diff --git a/Doc/Manual/SWIGPlus.html b/Doc/Manual/SWIGPlus.html index 0c259e393..2244a0508 100644 --- a/Doc/Manual/SWIGPlus.html +++ b/Doc/Manual/SWIGPlus.html @@ -3632,7 +3632,7 @@ Alternatively, you could expand the constructor template in selected instantiati // Create default and conversion constructors %extend pair<double, double> { - %template(paird) pair<double, dobule>; // Default constructor + %template(paird) pair<double, double>; // Default constructor %template(pairc) pair<int, int>; // Conversion constructor }; </pre> @@ -3647,7 +3647,7 @@ instead: <pre> // Create default and conversion constructors %extend pair<double, double> { - %template(pair) pair<double, dobule>; // Default constructor + %template(pair) pair<double, double>; // Default constructor %template(pair) pair<int, int>; // Conversion constructor }; </pre> diff --git a/Doc/Manual/Warnings.html b/Doc/Manual/Warnings.html index 0cf2a1066..02197f1cb 100644 --- a/Doc/Manual/Warnings.html +++ b/Doc/Manual/Warnings.html @@ -483,7 +483,7 @@ example.i(4) : Syntax error in input(1). <li>401. Nothing known about class 'name'. Ignored. <li>402. Base class 'name' is incomplete. <li>403. Class 'name' might be abstract. -<li>450. Deprecated typemap feature ($source/$target). +<li>450. Reserved <li>451. Setting const char * variable may leak memory. <li>452. Reserved <li>453. Can't apply (pattern). No typemaps are defined. diff --git a/Doc/Manual/Windows.html b/Doc/Manual/Windows.html index 001d0ef46..eae9ffb84 100644 --- a/Doc/Manual/Windows.html +++ b/Doc/Manual/Windows.html @@ -34,6 +34,7 @@ <li><a href="#Windows_swig_exe">Building swig.exe on Windows</a> <ul> <li><a href="#Windows_cmake">Building swig.exe using CMake</a> +<li><a href="#Windows_mingw_msys">Building swig.exe using MSYS2</a> <li><a href="#Windows_mingw_msys">Building swig.exe using MinGW and MSYS</a> <li><a href="#Windows_cygwin">Building swig.exe using Cygwin</a> </ul> @@ -250,7 +251,8 @@ For fully working build steps always check the Continuous Integration setups cur and save to a folder e.g. C:\Tools\Bison </li> <li> - Install PCRE using Nuget using the following command: <pre>C:\Tools\nuget install pcre -Version 8.33.0.1 -OutputDirectory C:\Tools\pcre</pre> + Install PCRE using Nuget using the following command: <pre>C:\Tools\nuget install pcre -Version 8.33.0.1 -OutputDirectory C:\Tools\pcre</pre>. + Alternatively, use <tt>WITH_PCRE</tt> option to disable PCRE support if you are sure not to need it. </li> <li> We will also need the SWIG source code. Either download a zipped archive from GitHub, or if git is installed clone the latest codebase @@ -296,7 +298,59 @@ swig.exe -help <pre>-python -c++ -o C:\Temp\doxygen_parsing.cpp C:\swig\Examples\test-suite\doxygen_parsing.i</pre> </div> -<H4><a name="Windows_mingw_msys">3.3.1.2 Building swig.exe using MinGW and MSYS</a></H4> +<H4><a name="Windows_mingw_msys">3.3.1.2 Building swig.exe using MSYS2</a></H4> + + +<p> +Download and install MSYS2 from <a href="https://www.msys2.org/">www.msys2.org</a> (tested with version msys2-x86_64-20201109). +Launch the MSYS2 shell. +</p> +<p> +Install the packages needed to build swig:<br> +</p> + +<div class="shell"> +<pre> +pacman -S git autoconf automake bison gcc make pcre-devel +</pre> +</div> + +<p> +Clone the repository to /usr/src/: +</p> + +<div class="shell"> +<pre> +mkdir /usr/src/ +cd /usr/src/ +git clone https://github.com/swig/swig.git +</pre> +</div> + +<p> +Configure and build: +</p> + +<div class="shell"> +<pre> +cd /usr/src/swig +./autogen.sh +./configure +make +</pre> +</div> + +<p> +Finally you may also want to install SWIG: +</p> + +<div class="shell"> +<pre> +make install +</pre> +</div> + +<H4><a name="Windows_mingw_msys">3.3.1.3 Building swig.exe using MinGW and MSYS</a></H4> <p> @@ -414,7 +468,7 @@ make </ol> -<H4><a name="Windows_cygwin">3.3.1.3 Building swig.exe using Cygwin</a></H4> +<H4><a name="Windows_cygwin">3.3.1.4 Building swig.exe using Cygwin</a></H4> <p> |